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Introduction 



This ViewPoint Programmer's Manual is written for programmers who are developing 
applications to run on ViewPoint software. Viewpoint's open architecture philosophy 
allows applications to be developed easily. 

You will find this manual useful only if you are already a Mesa programmer. You should 
have completed the Mesa Course and be familiar with the contents of the XDK User's 
Guide (610E00140) and the Mesa Language Manual (610E00170). You should also be 
familiar with the facilities described in the Pilot Programmer's Manual {610E00160) and 
the Filing Programmer's Manual contained in the Services Programmer's Guide 
(610E00180). 

The ViewPoint Programmer's Manual provides you with the information you will need to 
implement the us.er interface of an application that runs on ViewPoint. This includes 
information such as how to; 

Represent applications as icons. 

Interact with the mouse and keyboard to process the user's instructions. 
Create folder-like containers. 
Create property sheets. 
Create menus. 

Paint pictures and text on the display. 
Create programmable keyboards. 
Represent and manipulate multinational text. 
It does not provide you with Mesa, Pilot, or Services-specific information. 
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1.1 Document Structure 

This introductory chapter describes the physical manual itself, how it is organized, who 
should read it, how it should be read, and why. Chapter 2, Overview, describes ViewPoint 
and discuss its history and overall design 

Chapter 3, The Programmer's Guide, tells how to use the ViewPoint interfaces. It 
describes concepts essential to understanding ViewPoint and describes the facilities that 
are available. The most common interfaces are briefly discussed and grouped by 
application. All of the ViewPoint interfaces, with a short summary, are listed 
alphabetically at the end of the chapter 

The individual interface chapters are arranged alphabetically in Chapters 4 through 59. 
These chapters provide detailed descriptions of the interfaces that ViewPoint provides. 
Each interface chapter begins with an overview that explains the concepts behind the 
interface and the important data types that it manipulates. The second section of each 
chapter describes the actual items of the Mesa interface and groups them by function The 
third section explains typical ways of using the interface and often contains programming 
examples, and the fourth section is the index of interface items. Within an interface 
chapter, the items of the broadest interest are presented first; more specialized items 
follow later. 

Appendix A presents the system TIP Tables, references are in Appendix B, Appendix C 
contains a list of well-known Atoms, and Appendix D contains a listing of public symbols. 

1.2 Getting Started 

Chapters I, 2, and 3 of the ViewPoint Programmer's Manual should be read in order. 
Within Chapter 3, you will sometimes be guided to various sections in task-relative rather 
than page-relative order. Chapters 4 through 59 (the interface chapters) can be read in 
any order, depending on your need. 
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2.1 What Is Viewpoint? 

ViewPoint is a collection of facilities for writing application programs that run on a 
personal workstation with a high-resolution bitmap display. It supports an open-ended 
collection of applications, providing a framework and a set of rules that allow these 
independent applications to be integrated. It has an advanced user interface that also 
allows applications to be easily adapted for users in other countries. 

Throughout this document, the term user describes people who interact with the 
applications built on ViewPoint via the mouse and keyboard, User actions are not 
predictable or controllable by programs. The term client describes programs that use the 
facilities described in this document The client may act as a result of some user action, 
but the behavior of the client is the result of a program and under control of its 
implementor. 

2.1.1 User Abstractions 

ViewPoint uses several abstractions that are part of the advanced user interface pioneered 
by the Star Workstation: 

• Icons and Desktop. Icons that represent objects on a desktop are one basic abstraction 
These objects can represent either functions or data Data icons, such as a document, 
represent objects on which actions can be performed. Function icons, such as a printer, 
represent objects that perform actions. In the metaphor, thev are on the desktop that 
also serves as the background for their display. With ViewPoint, clients may create 
new icons that provide additional functions within the desktop metaphor. 

• Windows. Windows are rectangular areas on the screen that display the contents of an 
icon when it is opened. Each window has a header containing the name of the 
window's icon and a set of commands. The window also contains scroll bars that scroll 
the contents of the window vertically and horizontally 
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• Property Sheets. Property sheets are displayed forms that show the properties of an 
object. They contain several types of parameters, including state parameters, which 
may be on or off; choice parameters, which have a set of mutually exclusive values; 
and text parameters. 

• Selection. The selection is an object or body of data identified by the user. It is the 
target of user actions; there can be only one selection at any one time. It can be a string 
of text that the user may then delete, copy, or change the properties of. It can be an 
icon on the desktop that is moved to a printer icon for printing or opened to display its 
contents. In general, it can be almost any piece of data that can be represented on the 
screen. 



2.1.2 Client Abstractions 



To implement the above user abstractions and to provide some building blocks for 
developing applications, ViewPoint uses several client abstractions: 

• Containee and StarDesktop. Containee is an application registration facility that 
associates an application with a file type. Registering an application consists of 
providing procedures that paint iconic pictures and perform various operations. 
StarDesktop, using the desktop metaphor, displays the desktop window and iconic 
pictures for each file found in a particular directory. 

• Client Windows. The client window abstraction is more primitive than the user 
window abstraction. The client window abstraction serves to isolate applications from 
the physical display and each other. A window can be thought of as a quarter of an 
infinite plane. Within that space, the client is called upon to display the contents of the 
window without regard to any other applications' windows. Windows may be linked to 
form a tree structure. A user's window is typically composed of a number of small 
client windows-one for the header, one for each scroll bar, and so forth. 

• Menus. Menus are sequences of named commands, each consisting of a text name and 
a procedure. Menus may be displayed to the user in several forms, such as in a pop-up 
menu or as window shell header commands (see below). 

• Window Shells. The user window abstraction is implemented by window shells. They 
provide the header, scroll bars, and body windows. The body windows are windows the 
client uses to display the content of an application. The commands in the header are 
menus. 

• Form Windows. Form windows are the client abstraction that provides the basis for 
the user property sheet. Form windows allow form items in a window to be created and 
manipulated. There are several types of items: boolean items, choice items, text items, 
numeric text items, command items, form and window items. Window items allow the 
client to implement its own type of item. The property sheet user abstraction is 
implemented by putting a form window inside a window shell. 
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• Container Windows, Container windows implement a window that contains a list of 
items. Clients supply the source of items and the container window handles displaying 
the contents in a window and interacting with the user. 

• Selection. The client selection abstraction is a framework in which a client can 
manifest itself as the holder of the user's current selection while other clients 
interrogate the selection and request that it be converted to a variety of data types. 
ViewPoint defines several selection conversion types, but the selection framework 
allows clients to define additional conversion types. The selection is the principal 
means by which information is transferred between different applications. 



2.1.3 System Structure 



Viewpoint's architecture contains a small set of public interfaces that provide the basic 
facilities for building workstation applications. Facilities are included in ViewPoint for 
several reasons. Some facilities implement system-wide features, such as the window 
package. If several applications tried to implement their own window packages, chaos 
would result. Facilities are also included in ViewPoint to provide consistent user 
interface, such as form windows and property sheets. A final reason for including facilities 
is to provide packages that are useful to many clients, such as the simple text facilities. As 
ViewPoint evolves, more facilities useful to a variety of clients will be added. 

The ViewPoint interfaces fall into the following' general categories: 
Application registration: Containee 

Windows and display: Context, Display, StarWindowShell, Window 

Forms and property sheets: FormWindow, FoirmWindowMessageParse, PropertySheet 

User input and keyboards: BlackKeys, KeyboardKey, KeyboardWindow, LevellVKeys, 

SoftKeys,TIP, TIPStar 

Strings and messages: XChar, XCharSets, XCharSetNNN, XComSoftMessage, 

XFormat, XLReal, XMessage, XString, XTime, XToken 

Selection: Selection 

Containers: ContainerCache, ContainerSource, ContainerWindow, 

FileContainerShell, FileContainerSource 

Text display and editing: SimpleTextDisplay, SimpleTextEdit, SimpleTextFont 

Miscellaneous user interface: Attention, Cursor, MenuData, MessageWindow, 

PopupMenu, StarDesktop, Undo 

Miscellaneous: Atom, AtomicProfile, Event, IdleControl 



2.2 History 



ViewPoint is the result of past experience with Star and the Xerox Development 
Environment. In late 1982, the Star Performance and Architecture Project concluded that 
Star's monolithic system structure, in which every piece knew about every other piece, 
hindered its performance. The monolithic structure also made it difficult to develop new 
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applications. In addition, there were hundreds of interfaces in the system but no 
distinction between public and private interfaces, making it difficult for programmers to 
learn how to write applications in the system. 

In contrast to Star, the Xerox Development Environment had a modular system structure 
with a small number of well-documented public interfaces It also encouraged an 
open-ended collection of applications. While it performed well and was open, the Xero.x 
Development Environment did not have as consistent a user interface as Star, nor did it 
support Star's multinational requirements. 

As a result of this study, ViewPoint was created. It has the system structure, documented 
public interfaces, and openness of the Xerox Development Environment, yet supports 
Star's user interface and multinationality requirements. 

While it was initially focused on providing a new foundation for Star, ViewPoint has 
become the basis for more software products from the Office Systems Division. It will 
evolve to replace the current foundation of the Xerox Development Environment and will 
likely support products from organizations outside the Office Systems Division. 

2.3 Philosophy and Conventions 

Viewpoint's philosophy and conventions apply both to applications that interact with the 
user and to packages that implement some facility. Some are just good system building 
concepts. ViewPoint assumes that programs that run within it are friendly and that they 
are not trying to circumvent or sabotage the system. The system does not try to enforce 
many of these conventions but assumes that clients will adhere to them voluntarily. If 
these conventions are not followed, the system may degrade or break down altogether 

2.3.1 Supported Public Interfaces 

Systems should be designed to export public interfaces that are well documented and 
relatively stable. By defining a set of primitive facilities and stressing their stability, 
applications are encouraged to depend on the existing ViewPoint facilities rather than on 
other applications packages. This promotes an open architecture in which applications can 
be developed and loaded with relative ease, exchanging information among themselves 
while maintaining the independence of client modules. The open architecture allows 
designing for unknown applications as well as the class of applicciHons expected in Star 

In keeping with an open architecture, ViewPoint does not make far-reaching assumptions 
about the applications that run above it. While it provides facilities that make certain 
styles of applications easy, it does not preclude other styles of applications. 

2.3.2 Plug-ins 

ViewPoint is self-contained in that it does not import procedures that it expects a client to 
supply. Rather it waits, in effect, for clients to call it and state that they wanto to 
implement some facility. This is referred to as a plug-in approach; an application plugs 
itself in to a lower layer of software. 

Plug-ins encourage modularity at the client level. Since ViewPoint can be run by itself 
(although it does not do much), it can also be run with just one application plugged in. 
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Thus each application can be implemented and debugged individually, simplifying system 
development. 

Plug-ins also can break a dependency that would create a complex dependency graph. For 
example, the desktop has a dependency on the applications that appear in the desktop. If 
the desktop depended directly on the applications, it would have to change every time a 
new application was created By having the applications plug themselves into the desktop, 
the direct dependency is broken. 

2.3.3 Don*t Preempt the User 

Clients should avoid dictating what the user must do. The user should be free to interact 
with different applications as desired. For example, the current selection is something 
that the user should control. It should be changed only as a result of user actions. A 
background process should not change the selection out from under the user. 

2.3.4 Don't Call Us, We'll Call You 

Since the user is in control, a program must wait for the user to interact with it. The 
method of interacting with the user that is prevalent in terminal-oriented user interfaces 
is to get a command from the user and execute it, which results in the client regaining 
control while it awaits user input. With potentially multiple applications active 
simultaneously, the user should be free to interact with the one of his choosing. 
Viewpoint's input facilities notify a window when the user inputs to that window. 

Events are another case in which the system calls the client. For example, a client may 
need to do something when the user logs in. If the client registers a procedure with the 
appropriate event, the procedure is invoked when the event occurs. 
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This guide for ViewPoint application programmers is intended to point the programmer to 
the most important parts of the most important interfaces needed for writing an 
application in ViewPoint. 

ViewPoint is a collection of interfaces to be used for writing application programs. It is 
primarily intended to support applications like those in the ViewPoint workstation; that 
is, there is support for icons, windows, property sheets, and so forth. 

The first section (3.1 Guide) contains a jump table of the form, "If your application does X, 
then you use interfaces A and B, also you need to understand C and D, and you probably 
want to read section 3.1.x." The subsections (3.Lx) provide more detail about A, B, C, and 
D, pointing the programmer to the most important types and procedures in an interface. 
The second section (3.2 Getting Started) contains essential information for first-time 
ViewPoint programmers. Section 3.3 provides some flow of control descriptions for several 
common scenarios. It describes which interfaces call which client procedures when, and so 
forth. Section 3.4 discuss some programming conventions specific to ViewPoint interfaces. 
Section 3.5 contains a summary of all the ViewPoint interfaces. 



First, we briefly define an application from the user's point of view: The user sees the icons 
on the desktop, and can operate on them in various ways. He can select an icon with the 
mouse and open it to display its contents. Or by selecting the icon and pressing PROPS, he 
can examine and change the icon's properties through a window called a property sheet. 
After an icon is opened, he can examine the properties of the contents and change them by 
again using the property sheet. By selecting one icon, pressing COPY or MOVE, and then 
selecting another icon, he can perform various application-specific operations. This is 
often referred to as "dropping one icon onto another." Each application attaches a different 
meaning to the drop on operation. For example, the folder takes the icon dropped onto it 
and adds it to the folder. The printing application (printer icon) prints the icon dropped 
onto it. 



From the application's point of view, an icon is just a picture that represents a file. Files 
have a file type, and an application operates on all files of the same type. Thus when the 
user selects a folder icon, he is actually selecting a file with file type of folder. When the 
user performs some operation on an icon, the desktop calls the appropriate application 
based on the file type of the file represented by the selected icon. 
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3.1 Guide 

The following table can help you readily find a desired section. 

3.1.1 Guide to the Guide 

If your application ... See section 

... Appears as an icon: 

- Read about icon applications in 3.2 Getting Started 

- Use Containee to register the icon's behavior 

... Opens a window: 

- Use StarWindowShell to create a window 

- Use MenuData to construct menus 

... Manages the contents of a window: 

- Use Display and Window to display information 

- Supply a TIP. Notify Proc to process user actions 

- Use Selection to share data between applications 

- Use Context to save data with the window 

... Puts up a Property Sheet: 

- Use PropertySheet and Form Window interfaces 
... Manipulates strings: 

- Use the XString interfaces (including XFormat, XToken, XChar) 
... Displays messages to the user: 

- Use the XMessage and Attention interfaces 
... Displays a list of items like a folder: 

- Use the Container interfaces (GontainerWindow, ContainerSource) 
... Redefines the function keys: 

- Use the SoftKeys interface 
... Redefines the Black Keys: 

- Use BlackKeys and KeyBoardKey interfaces 



3.2.2 
3.1.2 



3.1.3 
3.1.4 



3.1.5 
3.1.5 
3.1.5 
3.1.5 



3.1.6 



3.1.7 



3.1.8 



3.1.9 



3.1.10 



3.1.11 
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3.1.2 Containee 



Containee is an application registration facility. An application is a software package that 
implements the manipulation of one type of file. Containee is a facility for associating an 
application with a file type. (§3.2.2 explains how an application registers itself and is then 
invoked to perform various operations). The most important items in Containee are: 



Implementation 

Setlmplementation 

GenericProc 

PictureProc 
Data, DataHandle 



A record containing several client procedures. 
Registers an application. 

Client procedure called to perform OPEN, PROPS, COPY/MO VE- 
onto, and so forth. 

Client procedure called to display an icon picture. 
Uniquely identifies a file. 



3.1.3 Application Windows 



StarWindowSheil allows a client to create a Star-like window. A StarWindowShell 
window has a header that contains a title, commands, and popup menus. The window may 
have scrollbars, both horizontal and vertical. It also has interior window space that may 
contain anything the client desires. StarWindowShell also supports the notion of opening 
within. 

A StarWindowShell is a window (see Window interface) that is a child of the desktop 
window. A StarWindowShell has an interior window which is a child of the 
StarWindowShell and is exactly the size of the available window space in the shell, that is, 
the window shell minus its borders and header and scrollbars. The interior window may 
have child windows created by the client. These children of the interior window are called 
body windows. The client may create an arbitrary number of body windows and may 
arrange them in an arbitrary fashion. Note: Since the body windows are children of the 
interior window, they are clipped by the interior window. 

Body windows may be managed directly by the client, including all display and 
notification (user input). (See §3.2.4). Body windows can also be managed by various 
interfaces provided by ViewPoint, such as FormWindow and ContainerWindow. These 
interfaces have Create procedures that take a body window and turn it into a particular 
kind of window, providing all the display and notification handling for the window. 



The most important items in StarWindowShell are: 

Create Creates a StarWindowShell window. 

CreateBody Creates a body window. 

ShellFromChild Returns the window shell, given a body window. 

SetRegularCommands Places commands in the header of a StarWindowShell. 
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AddPopupMenu Adds a popup menu to the header of a StarWindowShell. 

3.1.4 Menus 



A menu is a list of named commands. When the user selects a menu command, a client 
procedure is called. The MenuData interface allows menu items and menus to be created. 
MenuData does not address the user interface for menus. Menu items may appear as 
commands in the header of a star window shell (StarWindowShell. SetRegularCommands). 
Entire menus may be accessed via a popup symbol in the header of a window shell 
(starWIndowShell.AddPopupMenu). Menu items may be added to the popup menu that is 
available to the user through the attention window (Attention.AddMenultem). 

The most important items in MenuData are" 

Createltem Creates a menu item. 

MenuProc A client procedure that is called when the user selects a 

menu item. 

CreateMenu Creates a menu from an array of menu items. 



3.1.5 Managing a Body Window 

Clients can manage their own body windows. This involves handling both display and 
notification (user input), and often includes managing the current selection. Display is 
done by providing a window display procedure. Notifications are received through a client- 
provided Tip.NotifyProc. The current selection is managed using the Selection interface. 
Arbitrary data associated with a window can be saved with the window by using the 
Context interface. 



3.1.5.1 Display 



The client's display procedure is called by the Window interface to repaint the contents of 
the window. It is called when the window is initially made visible. It is also called when 
the window suddenly becomes more visible because an overlapping window was moved, or 
when the window is scrolled so that the part of it that was invisible before becomes visible. 
The display procedure should use the Display and/or SimpleTextDisplay interfaces to 
display bits in the window. The display procedure can be set when a window shell's body 
window is created (starWindowShell.CreateBody), or by calling window.SetDisplayProc. 

The most important item in Window is the client's display procedure. There is no type for 
this procedure, but it is discussed in the Window interface chapter. Other important 
items: 

Box Defines a rectangle in a window. 

Place Defines a point in a window. 
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The most important items in Display are: 

Black Displays a blaclc box. 

White Displays a white box. 

Invert Inverts the bits in a box. 

Bitmap Displays an arbitrary array of bits. 

The most important item in SimpleTextDisplay is: 

StringlntoWindow Displays a string in a window. 



3.1.5.2 TIP and TIPStar 



TIP provides basic user input facilities through a flexible mechanism that translates 
hardware- level actions from the keyboard and mouse into higher-level client action 
requests (result lists). The acronym TIP stands for terminal interface package. This 
interface also provides the client with routines that manage the input focus, the periodic 
notifler, and the STOP key. 

The basic notification mechanism directs user input to one of many windows in the 
window tree. Each window has a TiP.Table and a TiP.NotifyProc. The table is a structure 
that translates a sequence of user actions into a sequence of results which are then passed 
to the notify procedure of the window. 



The Notifier process dequeues user events, determines which window the event is for, and 
tries to match the events in the window's Table. If it flnds a match in the table, it calls the 
window's NotifyProc with the results specified in the table. If no match is found, it tries 
the next table in the window's chain of tables. If no match is found in any table, the event 
is discarded. 

TIP tables provide a flexible method for translating user actions into higher-level client- 
defined actions. They are essentially large select statements with user actions on the left 
side and a corresponding set of results on the right side. Results may include mouse 
coordinates, atoms, and strings for keyboard character input. 

ViewPoint provides a list of normal tables that contain one production for each single user 
action. Client programmers can write their own table to handle special user actions and 
link it to system-defined tables, letting those tables handle the normal user actions. These 
system-defined tables are accessible through the TIPStar interface and are described in 
Appendix A. 

Input Focus. The input focus is a distinguished window that is the destination of most user 
actions. User actions may be directed either to the window with the cursor or to the input 
focus. Actions such as mouse buttons are typically sent to the window with the cursor. 
Most other actions, such as keystrokes, are sent to the current input focus. Clients may 
make a window be the current input focus and be notified when some other window 
becomes the current input focus. 
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The current selection and the current input focus often go together. If the window in which 
a selection is made also expects to receive user keystrokes (function keys as well as black 
keys), TiP.SetlnputFocus should be called at the same time as Selection. Set is called. This is 
also the time to call SoftKeys.Push or KeyboardKey.RegisterClientKeyboards, if necessary. 

Modes. TIPStar also provides the notion of a global mode to support MOVE, COPY, and same. 
When the user presses down and releases the MOVE, COPY, or SAME keys, the client that 
currently has the input focus will receive the notification and should call TiPStar.SetMode. 
This changes the mouse TIP table so that atoms specific to the mode are produced rather 
than normal atoms when the user performs mouse actions. For example, in copy mode 
"CopyModeDown" instead of "PointDown" is produced when the left mouse button is 
pressed down. This informs the client that receives the atom that it should attempt to copy 
the current selection rather than simply select something. 

The most important items in TIP are: 

NotifyProc Client procedure that is called to handle a user action. 

Results, ResultObject Right side of the table entry that matched the user action. 
SetlnputFocus Sets a window to be the current input focus. 

The most important items in TIPStar are: 

NormalTable Returns the chain of system-provided TIP tables. 

SetMode Sets the entire environment into MOVE, COPY, or sameAs 

mode, thus changing the results produced for mouse clicks. 



3.1.5.3 Context 



The Context interface allows arbitrary client data to be associated with a window. Client 
data is usually allocated and associated with the window when the window is created. The 
data may be retrieved any time, such as at the beginning of the client's display procedure 
and TIP. NotifyProc. 

The most important items in Context are: 

Create Associates data with a window. 

Find Recovers the data previously associated with a window. 



3.1.5.4 Selection 



The Selection interface defines the abstraction that is the user's current selection. It 
provides a procedural interface to the abstraction that allows it to be set, saved, cleared, 
and so forth. It also provides procedures that enable someone other than the originator of ^Ipl^ 
the selection to request information relating to the selection and to negotiate for a copy of j 
the selection in a particular format. 
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The Selection interface is used by two different classes of clients. Most clients wish merely 
to obtain the value of the current selection in some particular format; such clients are 
called requestors. These programs call Convert (or maybe ConvertNumber, which in turn 
calls Convert), or Query, or Enumerate. These clients need not be concerned with many of 
the details of the Selection interface. 

The other class of clients are those that own or set the current selection; these clients are 
called managers. A manager calls Selection.Set and provides procedures that may be called 
to convert the selection or to perform various actions on it. The manager remains in 
control of the current selection until some other program calls Selection.Set. These clients 
need to understand most of the details of the Selection interface. 

A client that is managing its own body window will be both a selection requestor and a 
selection manager in different parts of the code. For example, when the user selects 
something in another window and copies it to the client's window, the client must call 
Selection.Convert to request the value of the selection in a form appropriate to the 
application. On the other hand, when the user clicks a mouse button in the client's 
window, the client will usually become the selection manager by calling Selection.Set. 

The most important items in Selection are: 

Convert Request the value of the selection in some target form. 

Value A record containing a pointer to the converted selection 

value, among other things. 

CanYouConvert Returns true if the selection manager can convert the 

selection to a particular target type. 

Set Called by a selection manager to become the current 

manager. 

ConvertProc Manager-supplied procedure that will be called to convert 

the selection to some target type. 

ActOnProc Manager-supplied procedure that will be called to perform 

some action on the selection, such as mark, unmark, clear, 

3.1.6 Property Sheets and FormWindow 

A property sheet shows the user the properties of an object and allows the user to change 
these properties. Several different types of properties are supported. The most common 
ones are boolean, choice (enumerated), and text. 
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From a client's point of view, a property sheet is simply a StarWindowShell with a 
FormWindow as a body window. A property sheet is created by calling PropertySheet.Create, | 
providing a procedure that will make the form items in the FormWindow (a 
FormWindow. MakeltemsProc), a list of commands to put in the header of the property sheet, 
such as Done, Cancel, and Apply (PropertySheet.Menultems), and a procedure to call when 
the user selects one of these commands (a PropertySheet.MenultemProc). When the user 
selects one of the commands in the header of the property sheet, the client's 
PropertySheet.MenultemProc is called. If the user selected Done, for example, the client can 
then verify and apply any changes the user made to the object's properties. 

The most important items in Property Sheet are: 

Create Creates a property sheet. 

Menultems Used for specifying which commands to put in the header of 

the property sheet. 

MenultemProc Client procedure called when the user selects one of the 

commands in the header. 

The most important items in FormWindow are: 
MakeltemsProc 



MakeXXXItem 



GetXXXItemValue Returns the current value of an item. XXX can be Boolean, 

Choice, Text, Integer, Decimal, Window, TagOnly, 
Command. 

3.1.7 XString, et al. 

The Xerox Character Code Standard defines a large number of characters, encompassing 
not only familiar ASCII characters but also Japanese and Chinese Kanji characters and 
others to provide a comprehensive character set able to handle international information 
processing requirements. Because of the large number of characters, the data structures 
in XString are more complicated than a long string's simple array of ASCII characters, but 
the operations provided are more comprehensive 

Characters are 16-bit quantities that are composed of two 8-bit quantities, their character 
set and character code within a character set. The Character Standard defines how 
characters may be encoded, either as runs of 8-bit character codes of the character set or as 
16-bit characters where the character set and character code are in consecutive bytes. (See 
the XChar chapter for information and operations on characters.) 

ViewPoint provides a string package consisting of several interfaces that support the 
Xerox Character Code Standard. XString provides the basic data structures for 
representing encoded sequences of characters and some operations on these data 
structures. XFormat converts other types into XStrings. XToken parses XStrings into other 
TYPES. XChar defines the basic character type and some operations on it. XCharSets 



Client procedure called to create the items m the form. 

Makes a form item. XXX can be Boolean, Choice, Text, 
Integer, Decimal, Window, TagOnly, Command. 
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enumerates the character sets defined in the Standard. A collection of interfaces 
enumerate the character codes of several common character sets (XCharSetNNN). XTime 
provides procedures to acquire and edit times into XStrings and XStrings into times. 

3.1.8 XMessage and Attention 

XMessage supports the translation into other languages of text displayed to the user. This 
is accomplished by not including any string constants in the code of an application. 
Rather, all the string constants for an application are declared in a separate module and 
registered with XMessage. Then whenever the application needs a string constant, it 
obtains it by calling XMessage.Get. Several commonly used messages such as "Yes", "No", 
and days of the week are defined in XComSoftMessage. 

The most important items in XMessage are; 

Get Retrieves a message. 

RegisterMessages Registers all the messages for an application. 

The Attention interface provides a global mechanism for displaying messages to the user. 
Attention provides procedures to post messages to the user in the attention window, clear 
the attention window, post a message and wait for confirmation, and so forth. 

The most important items in Attention are: 

Post Posts a message in the attention window. 

Clear Clears the attention window. 

formatHandle XFormat.Handlethat may be used to format strings into the 

attention window. 

3.1.9 Containers 

The Container interfaces (ContainerSource, ContainerWindow, FiieContainerSource, 
FileContainerShell, and ContainerCache) provide the services needed to implement an 
application that appears as an ordered list of items to be manipulated by the user. Star 
Folders are a typical example of such an application. 

Figure 3-1 shows the relationships among the various interfaces and potential clients. 
Each interface is described below, followed by a discussion of which interfaces an 
application might need to use. 
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Figure 3.1 Container Interface Dependencies 



The ContainerWindow interface takes a window and a ContainerSource and makes the 
window behave like a container. It maintains the display and manages scrolling, 
selection, and notifications. Note: This interface does not depend on NSFiie. 



A container source is a record of procedures that implement the behavior of the items in a 
container and the behavior of the container itself. ContainerWindow obtains the strings of 
each item by calling one of these procedures. ContainerWindow also performs user 
operations on items, such as open, props, delete, insert, take the current selection, and 
selection conversion by calling other procedures in the record. A container source can be 
thought of as a supply (source) of items for a container window. The ContainerSource 
interface defines each of the procedure types that a container source must implement. 
ContainerSource contains types only. 

ContainerCache provides the implementor of a container source with an easy-to-use cache 
for storing and retreiving the strings of each item and some client-specific data about each 
item. 

FileContainerSource provides an NSFile-backed container source. It takes an 
NSFile. Reference for a file that has children and each child file becomes an item of the 
container. Facilities are provided to specify the columns based on NSFiie attributes. 

The FileContainerShell interface takes an NSFiie and column information (such as 
headings, widths, formatting), and creates a FileContainerSource, a StarWindowShell, 

and a container window body window. Most NSFile-backed container applications can use 
this interface, thereby greatly simplifying the writing of those applications. 
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Each of the items in a container must behave like to a file on the desktop; that is, each 
item must be able to be opened, show a property sheet, take a selection, and so forth. 
However, the items need not be backed by files. If the container is backed by an NSFile that 
has children, then the FileContainerShell interface is the only interface the client needs to 
use. Otherwise, the client must implement a container source and must make most of the 
calls that the FileContainerShell implementation makes; that is, StarWindowShell. Create, 
StarWmdowShell.CreateBody, ContainerWindow.Create. 



3.1.10 SoftKeys 



The SoftKeys interface provides for client-defined function keys designated to be the 
isolated row of function keys at the top of the physical keyboard. It also provides a 
SoftKeys window whose "keytops" may be selected with the mouse to simulate pressing of 
the physical key on the keyboard. Such a window is displayed on the user's desktop 
whenever an interpretation other than the default SoftKeys interpretation is in effect. 
(The default is assumed to be the functions inscribed on the physical keys.) 



The most important items in SoftKeys are; 

Labels, Label Record Strings to display on the keytops in the SoftKeys window. 
Push Install a client-specific interpretation for the soft keys. 

Remove Remove a previously installed interpretation. - 

3.1.11 Client-Defined Keyboards 



KeyboardKey is a keyboard (the central set of black keys on the physical keyboard) 
registration facility. It provides clients with a means of registering system-wide 
keyboards (available all the time, like English, French, European), a special keyboard 
(like Equations), and/or client- specific keyboards (those that are available only when the 
client has the input focus). The labels from these registered keyboards are displayed in the 
softkeys window when the KEYBOARD key is held down by the user. 

The BlackKeys interface provides the data structures that define a client keyboard. 

The most important items in KeyboardKey are: 

AddToSystemKeyboards Adds a keyboard to the system keyboards. 
RegisterClientKeyboards Establishes the keyboards available to the user. 

The most important items in BlackKeys are: 

Keyboard, KeyboardObject A keyboard interpretation. 
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3.2 Getting Started 1^ 

This section is a guide for programmers who have never used the ViewPoint interfaces. It 
shows how two common types of applications are written using ViewPoint. 

There are two ways that a user invokes a program in the ViewPoint environment. First is 
to select an icon and press a function key such as OPEN, PROPS, COPY, or MOVE. This type of 
program is called an icon application. Second, the user may also invoke a program by 
simply selecting an item in the attention window's popup menu. For example, in OS 5, a 
Show Size command reports on the size of the selected icon's file. The following sections 
describe how to write each of these types of programs. 

3.2.1 Simplest Application 

The simplest way to get a program running in the ViewPoint environment is to have the 
program add an item to the attention window's popup menu. When the user selects that 
item, the program is called. See the SampleBWSTool for an example of this type of 
application. Excerpts from SampleBWSTool: 

Init: PROCEDURE = { 

sampleTool: xstring.ReaderBody <-xstring.FromSTRING("Sample Tool"L]; 
Attention.AddMenultem [ 

MenuOata.Createltem [ ^mtf*^ 

zone: sysZ, I 

name: @sampleTool, 

proc: MenuProc ] ]; 

}; 

Mainline code 
Initn; 

When the application is started, its startup (mainline) code creates a MenuData.ltemHandle 
by calling MenuOata.Createltem, then adds this item to the attention window's menu by 
calling Attention.AddMenultem. Now the MenuProc passed to MenuOata.Createltem will be 
called when the user selects the Sample Tool item in the attention window's popup menu. 
The MenuProc can then do whatever is appropriate for the application. 

3.2.2 Icon Application 

Getting an icon application running in ViewPoint is a little more complex. The basic idea 
is that an application operates on files of a particular type. When an application is started, 
it registers its interest in files of that type. Then whenever the user operates on a file of 
that type, the application gets called. Here is a skeletal example of some application code, 
the full explanation follows: 

-- Constants and global data 

samplelconFileType: NSFiie.Type = . . .; 

oldlmpi, newlmpi: Containee. Implementation <— []; 
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" Containee. Implementation procedures 
GenericProc: Containee.GenericProc = { 

SELECT atom FROM 

canYouTakeSelection = > . . . 
takeSelection = > . . . 
takeSelectionCopy a > . . . 
open « > . . . 
props a > . . . 

ENDCASE = > . , . 

PictureProc: Containee.PictureProc a { 
oisplay.Bitmap [. . .]; 

}';' 

" Initialization procedures 

InitAtoms: procedure = { 

open «-Atom.MakeAtom["Open"L]; 
props ^Atom.MakeAtom("Props"L]; 

canYouTakeSelection '«-Atom.MakeAtom["CanYouTakeSelection"L]; 
takeSelection <~ Atom. MakeAtom["TakeSelection"Ll; 
takeSelectionCopy Atom. MakeAtom("TakeSelectionCopy"L]; 

}; 

FindOrCreatePrototypelconFile: procedure = {...}; 

Setlmplementation: PROCEDURE a { 
newlmpl.genericProc <f-- GenericProc; 
newlmpl.pictureProc <— PictureProc; 

oldlmpi '<—Containee. Setlmplementation [ samplelconFileType, newlmpi ]; 

}; 

— Mainline code 
InitAtomsH; 

FindOrCreatePrototypekonFileH; 
Setlmplementation[]; 

The most important thing to note in the above example is the Setlmplementation 
procedure and the call to Containee. Setlmplementation in particular. This call associates 
the application's implementation (newlmpi) with a particular file type 
(samplelconFileType). This implementation is actually a Containee. Implementation that is 
a record which contains procedures. Whenever the user operates on files of type 
samplelconFileType, the procedures in the Implementation record are called. An 
understanding of how this works requires an understanding of how the ViewPoint desktop 
implementation operates. 

First, some background about NSFiles. All NSFiles have: 

• a name 

♦ a file type (long cardinal) 
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• a set of attributes, such as create date 

• either: 

• content, such as a document 

• children that are also NSFiles, such as a folder 

An NSFile that has children is often called a directory. Fine point: anNSFIIe can actually have both 
content and children, but we ignore that for now to simplify this discussion. Note that since the children 

of an NSFile can themselves have children, NSFile supports a hierarchical file system. 

A ViewPoint desktop is an NSFile that has children. Each child file of the desktop's NSFile 
is represented on the screen by an icon picture. The desktop display of rows of icons is an 
illusion. The word "icon" is in quotes because, from the programmer's point of view, there 
really is no such thing as an icon. The only things that really exist are files (NSFiles), icon 
pictures, and application code. 

Immediately after logging on, the desktop implementation enumerates the child files of 
the desktop file and calls an application's Containee.PictureProc for each child file, based on 
the child file's type. Each application's Containee.PictureProc should then display the icon 
picture for that file. 

After logon is complete and the desktop is displayed, the desktop implementation receives 
user actions such as mouse clicks and pressing the OPEN or PROPS keys. For example, 
assume the user selects an icon picture and presses OPEN. When the user presses OPEN, the 
desktop implementation determines the file type for the file represented by the icon 
picture the user selected, then calls the Containee.GenericProc for the application that 
operates on files of that type, requesting that the application open the icon. It also passes 
the application a unique identifier for the particular file selected. At this point the 
application can do whatever is appropriate for that application. Typically, the application 
opens the file, reads some data out of the file, creates a StarWindowShell, and displays the 
contents of the file in the window in some application-specific form. 

The desktop implementation does not call an application directly. Rather, ViewPoint 
maintains a table of file-type/Containee. Implementation pairs. When an application calls 
Contalnee.Setlmplementation, an entry is added to the table. When the desktop 
implementation calls an application, it obtains the Containee. Implementation for the 
application by looking it up in the table (it actually calls Containee. Getlmplementation). 



3.2.3 Operational Notes 



To write an icon application, a programmer must obtain a unique file type. Contact your 
ViewPoint consultant to obtain one. 

In the example above, the application in its initialization code checks to be sure a 
prototype file exists and, if not, creates one. This usually involves creating a file with the 
proper file type for this application. This allows the user to get started with the 
application, usually by copying the blank prototype out of a special folder of prototypes. 
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Note: There is a clear distinction between a prototype file for an application and a bed file 
that contains the code for the application. All bed files are of the same type, while each 
prototype file is different for each application. 

3.3 Flow Descriptions 

The following flow descriptions are intended to show how everything ties together. For 
each example scenario, the exact sequence of calls is described, including ViewPoint 
interfaces and clients. 



3.3.1 Select an Icon 

The user points at an icon on the desktop. 

• When the mouse button goes down over an icon picture, the notification goes to the 
desktop implementation's TiP.NotifyProc. The NotifyProc will be passed a window. Place 
and a "PointDown" atom. The desktop implementation determines what file is 
represented by that icon picture. Fine Point: The desktop implementation maintains a mapping 
from icon picture locations to NSFile. References. 

• The desktop implementation calls Containee.Getlmplementation, passing in the file 
type of the file and getting back the Containee. Implementation for that file type. 

• The desktop implementation calls the Containee. PictureProc that is in the 
Implementation; i.e., impl.pictureProc, passing in 

• data : the NSFile. Reference for the file 

• old: normal 

• new: highlighted 

• The application's PictureProc displays a highlighted version of its icon picture, 
perhaps simply calling Display. Invert. 

• When the mouse button goes up (a "PointUp" atom), the desktop implementation 
becomes the current selection manager by calling Selection. Set. It sets the desktop 
window to be the current input focus by calling tip. SetlnputFocus. Setting the input 
focus to be the desktop window ensures that keys such as OPEN, PROPS, COPY, etc,, will 
all go to the desktop's NotifyProc. 

• END 

3.3.2 PROPSof an Icon 

Assume an icon on the desktop is selected. The user presses PROPS. After changing some 
items in the property sheet, the user selects Done. 

• The desktop implementation's TiP.NotifyProc gets the notification (a "PropsDown" 
atom) and determines which icon picture is currently selected and what file is 
represented by that icon picture. 
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• The desktop implementation calls Containee.Getlmplementation, passing in the file 
type of the file and getting back the Containee.lmplementation for that file type. 

• The desktop implementation calls the Containee.GenericProc that is in the 
Implementation; i.e., impl.genericProc, passing in: 

• data: the NSFile. Reference for the file 

• atom: "Props" 

• changeProc: a Containee.ChangeProc that belongs to the desktop implementation 

• changeProcData: a pointer to some desktop implementation data that identifies 
the icon/file being operated on 

• The application's GenericProc creates a property sheet by calling PropertySheet.Create. 
It probably also opens and retrieves some data out of the file (using various NSFile 
operations) and uses that data to set the initial values of the items in the property 
sheet. 

• Typically, the client will want to save the NSFile. Handle for the file while the property 
sheet is open. In addition, if the opening and closing of the property sheet might cause 
the file's attributes to change, the application's GenericProc must save the passed 
changeProc and changeProcData. A typical example is when the file's name is one of 
the items in the property sheet and the user can change the name. This data is saved 
by allocating a record with this data in it and passing a pointer to the record as the 
clientOata parameter to PropertySheet.Create Later, when the user selects Done or 
Apply, this data may be recovered (see the rest of this How description). Note: This 
data cannot be saved in a local frame (such as that of the GenericProc) since the 
GenericProc must return to the notifier after creating the property sheet, and when 
the user selects Done or Apply that is a new call stack. The client data should not be 
saved in a global frame either, because there may be more than one property sheet 
open at a time for a particular application. 

• The application's GenericProc returns the starWindowSheil.Handle for the property 
sheet. 

• The desktop implementation displays the property sheet by calling 
StarWindowShell.Push, then the desktop's NotifyProc returns to the notifier. 

• The user changes some items and then selects Done. 

• The PropertySheet implementation calls the client's PropertySheet.MenultemProc that 
was passed in to PropertySheet.Create, passing in. 

• shell: the StarWindowShell for the property sheet 

• formWindow: the FormWindow for the property sheet 

• menultem: done 

• clientData: the pointer to the client's data that was passed to PropertySheet.Create. 

• The client's MenultemProc recovers the client's data (the file handle, the changeProc 
and changeProcData, and any other relevant client data) from the clientData 
parameter. It determines if the user made any changes and, if so, updates the file 
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accordingly and calls the changeProc, passing in the changeProcData, the file 
reference, and a list of the changed file attributes. 

The desktop's ChangeProc causes the icon picture to be redisplayed, since changing an 
attribute such as the name requires the picture to be updated with the new name. 

The client's MenultemProc returns to the PropertySheet implementation, indicating 
that the property sheet should be destroyed. 

The PropertySheet implementation destroys the property sheet by calling 
StarWindowShell.Pop and returns to the notifier. 

END. 

3.3.3 OPEN an Icon 

Opening an icon is similar to opening a property sheet for an icon. 

3.3.4 COPY Something to an Icon 

Assume something has been selected. The user presses COPY and, then points at an icon. 

• When COPY is pressed, the NotifyProc for the window that currently has the input 
focus (and the selection) is called. It calls TiPStar.SetMode [copy] to set the 
environment into copy mode and then returns to the notifier. It might also call 
Cursor. Set to change the cursor shape to indicate move mode. 

• SetMode will replace the NormalMouse.TIP table with the CopyModeMouse.TIP table. 

• The user presses the mouse button down over an icon on the desktop. 

• The desktop's NotifyProc gets called with a "CopyModeDown" atom (instead of a 
"PointDown" atom because of the TIP table switch). It determines what file is 
represented by the icon picture the user is pointing at. It calls 
Containee.Getlmplementation, passing in the file's type and getting back a 
Containee.lmplemeritation. It calls the Implementation's GenericProc passing in; 

• data: the NSFile.Reference for the file 

€> atom: "CanYouTake" 

• The application's GenericProc calls Selection. CanYouConvert or Selection. HowHard to 

determine if the current selection can be converted to target type(s) that the 
application can take. For example, if the icon being copied to is a printer icon, it will 
call HowHard with targets of interpressMaster and file. 

• The current selection manager's Selection. ConvertProc is called by the Selection 
implementation and returns an indication of how hard it would be to convert the 
selection to the given target types. 

• The application's GenericProc returns a pointer to true if it determines that it can take 
the current selection and false if it cannot. 
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• The desktop implementation changes the cursor shape to a question mark if the 
application's GenericProc returns false. Otherwise, it leaves the cursor as it was. 

• Now the user lifts up the mouse button. 

• The desktop's NotifyProc gets called with a "Copy Mode Up" atom. It determines what 
file is represented by the icon picture the user is pointing at. It calls 
Containee.Getlmplementation passing in the file's type and getting back a 
Containee.lmplementation. It calls the Implementation's GenericProc, passing in: 

• data: the NSFiie. Reference for the file 

• atom: "TakeSelectionCopy" 

• changeProc: a Containee.ChangeProc that belongs to the desktop implementation 

• changeProcData: a pointer to some desktop implementation data that identifies 
the icon/file being copied to 

• The application's GenericProc calls Selection, Convert or (Selection. Enumerate) to convert 
the selection to the desired type. The application then operates on the converted 
selection value as appropriate for that application. For example, the printer icon 
application would convert the selection to an interpressMaster and send the master to 
the printer. (See the Selection chapter for a full flow description of the selection 
mechanism.) 

• The application's GenericProc returns to the desktop's NotifyProc, which returns to 
the notifier. 

• END. 

3.4 Programming Conventions 

The ViewPoint environment assumes that the programs that run in it are friendly and 
that they are not trying to circumvent or sabotage the system. The system does not enforce 
many of the conventions described here but assumes that application programmers will 
adhere to them voluntarily. If these conventions are not followed, the ViewPoint 
environment may degrade or break down altogether. 

The most important principle is that users should have complete control over their 
environment. In particular, clients shall not pre-empt users. A user should never be forced 
by a client into a situation where the only thing that can be done is to interact with only 
one application. Furthermore, the client should avoid falling into a particular mode when 
interacting with the user; that is, an application should avoid imposing unnecessary 
restrictions on the permitted sequencing of user actions. 

This goal of user control has implications for the designs of applications. A client should 
never seize control of the processor while getting user input. This tends to happen when 
the client wants to use the "get a command from the user and execute it" mode of 
operation. Instead, an application should arrange for ViewPoint to notify it when the user 
wishes to communicate some event to the application. This is known as the "Don't call us, 
we'll call you" principle. 
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The user owns the window layout on the screen. Although it is possible for the client to 
rearrange the windows, this is discouraged. Users have particular and differing tastes in 
the way they wish to lay out windows on the display; it is not the client's role to override 
the user's decisions. In particular, clients should avoid making windows jump up and 
down to try to capture the user's attention. If the user has put a window off to the side, 
then he does not want to be bothered by it. 



3.4.1 Notifier 



ViewPoint sends most user input actions to the window that has set itself to be the focus 
for user input; the rest of the actions are directed to the window containing the cursor. (See 
the TIP interface for details on how the decision is made where to send these actions.) A 
process in ViewPoint notes all user input actions and determines which window should 
receive each one. A client is concerned only with the actions that are directed to its 
window and need not concern itself with determining which actions are intended for it. 

The basic notification mechanism directs user input to one of many windows in the 
window tree. Each window has a TIP.Table and a TIP.NotifyProc. The table is a structure 
that translates a sequence of user actions into a sequence of results that are then passed to 
the notify procedure of the window. 

There are two processes that share the notification responsibilities, the Stimulus process 
and the Notifier process. The Stimulus process is a high-priority process that wakes up 
approximately 50 times a second. When it runs, it makes the cursor follow the mouse and 
watches for keyboard keys going up or down, mouse motion, and mouse buttons going up 
or down, enqueuing these events for the Notifier process. 

The Notifier process dequeues these events, determines which window the event is for, 
and tries to match the events in the window's table. If it finds a match in the table, it calls 
the window's notify procedure with the results specified in the table. If no match is found, 
it tries the next table in the window's chain of tables. If no match is found in any table, the 
event is discarded. 

The Notifier process is important. To avoid multi-process interference, some operations in 
the system are restricted to happening only in the Notifier process. Setting the selection is 
one such operation. The Notifier process is also the one most closely tied to the user. The 
Notifier waits until a NotifyProc finishes for one user action before processing the next 
user action. If an operation will take an extended time to complete (more than three to five 
seconds), it should be forked from the notifier process to run in a separate process so that 
the Notifier process is free to respond to the user's actions. Of course, the application 
writer must take great care when stepping into this world of parallel processing. 



3.4.2 Multiple Processes, Multiple Instances 



ViewPoint makes it possible to have many programs running simultaneously. The 
designer of a client-callable package should bear in mind that his package may be invoked 
by several different asynchronous clients. One implication of this constraint is that a 
package should be monitored. 

The simplest design is to have a single entry procedure that all clients must call. While 
one client is using the package, all other clients will block on the monitor lock. Of course, 
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no state should be maintained internally between successive calls to the package, since 
there is no guarantee that the same client is calling each time. 

This simple approach has the disadvantage that clients are simply stopped for what may 
be a long time, with no option of taking alternate action. This restriction can be eased by 
having the entry procedure check a "busy" bit in the package. If the package is busy, the 
procedure can return this result to the client. The client can then decide whether to give 
up, try something else, or try again. This flexibility is less likely to tie up an application 
for a long period, and the user can use the application for other purposes. 

If the package is providing a collection of procedures and cannot conform to the constraint 
that it provide its services in a single procedure, the package and its clients must pass 
state back and forth in the form of an object. The package can use a single monitor on its 
code to protect the object, or it can provide a monitor as part of each object. If it does the 
latter, then several clients can be executing safely at the same time. 

Some packages require that a client provide procedures that will be called by the package. 
The designer of such a package should have these client-provided procedures take an extra 
parameter, a long pointer to client instance data. When the client provides the package 
with the procedures, it also provides the instance data to pass to the procedures when they 
are called. This instance data can then be used by the client to distinguish between several 
different instances of itself that are sharing the same code. 

3.4.3 Resource Management 

Programs in the Xerox Development Environment must explicitly manage resources. For 
example, memory is explicitly allocated and deallocated by programs; there is no garbage 
collector to reclaim unused memory. All programs share the same pool of resources, and 
there is no scheduler watching for programs using more than their share of execution 
time, memory, or any other resource. 

Programs must manage resources carefully. If a program does not return a resource when 
it is done with it, that resource will never become available to any other program and the 
performance of the environment will degrade. The most common resource, and one of the 
more difficult to manage, is memory. 

When interfaces exchange resources, clients must be very careful about who is responsible 
for the resource. We say that the program that is responsible for the deallocation of a 
resource is the owner of that resource. One example of a resource is a file handle. If a 
program passes a file handle to another program, both programs must agree about who 
owns that file handle. Did the caller transfer ownership by passing the file handle, or is it 
retaining ownership and only letting the called procedure use the file handle? If there is 
disagreement between the two programs, either the file will be released twice, or it will 
never be released at all. All interfaces involving resources must state explicitly whether 
ownership is transferred. To ease the problem of memory management when the 
ownership of memory can change, called the system heap is a common heap used in 
ViewPoint. If a piece of memory can have its ownership transferred, it is either allocated 
from the system heap or a deallocation procedure must be provided for it. 

The most common resource appearing in interfaces is an XString (Reader or ReaderBody). 
There must be agreement about which program is responsible for deallocating the string's 
bytes. Typically, a string passed as an input parameter does not carry ownership with it; 
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implementors of such procedures should not deallocate or change the string. If it is 
necessary for the implementor to modify the string or use it after the procedure returns, 
the implementor should first copy it. Clients should be particularly careful when a 
procedure returns a string to note whether ownership has come with it. 



3.4.4 Stopping Applications 

The Viewpoint environment consists of cooperating processes. There are no facilities for 
cleanly terminating an arbitrary collection of processes. It is assumed that application 
writers will be good citizens and design their tools to stop voluntarily when asked to stop. 

An application should stop if the user aborts the application. There are two ways to 
determine if the user has aborted an application. An application's window can have a 
TIP.AttentionProc that will be called as soon as the user presses the STOP key. Or, 
procedures in the TIP interface can check whether a user has aborted an application with 
the STOP key in the application's window. An application should check for a user abort at 
frequent intervals and be prepared to stop executing and clean up after itself. Because the 
application controls when it checks, it can check at points in its execution when its state is 
easy to clean up. Packages that can be called from several programs should take a 
procedure parameter that can be called to see whether the user has aborted. 



3.4.5 Multinationality 

ViewPoint is designed to support easy transport of applications to other countries. The 
string package (XString, XChar, XFormat, etc.) supports the Xerox Character Code 
Standard, which allows for strings in many languages to be intermixed. The XMessage 
interface supports the translation of user messages into other languages by allowing the 
application programmer to put all these messages into a module separate from the rest of 
the application code. The KeyboardKey interface supports the addition of keyboards for 
many languages. 



Application programmers are strongly encouraged to allow their application to be 
multinational. This means for example, using XString for all string operations and using 
XMessage to manage any text that will be displayed to the user. It also means not making 
any language assumptions about characters received from the user. An application that 
expects typing input from the user should be prepared to receive characters from any 
character set. 



3.5 Summary of Interfaces 



Atonn provides the mechanism for making TIP, Event, and Containee atoms. 
AtomicProfile provides a mechanism for storing and retrieving global values. 
Attention provides a means of displaying messages to the user. 



BlackKeys provides the capability to change the interpretation of the central (black) 
section of the keyboard. 
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Containee is an application registration facility. It allows an application to register its 
implementation for files of a particular type. 

ContainerCache provides a simple cacheing mechanism for the implementor of a container 
source. 

ContainerSource defines the procedures that must be implemented to provide a source of 
items for a container window. 

ContainerWindow creates a window that displays an ordered list of items that behave like 
icons on a desktop. 

Context provides a mechanism for clients to associate data with windows. 

Cursor provides facilities for a client to manipulate the appearance of the cursor that 
represents the mouse position on the screen. 

Display provides facilities to display bits in windows. 

Event provides clients with the ability to be notified of events that take place 
asynchronously on a system-wide basis. 

FileContainerSheil creates a StarWindowShell with a ContainerWindow as a body 
window that is backed by a FileContainerSource. 

FileContainerSource creates a container source that is backed by a file that has children. 

FormWindow creates a window with various types of form items in it, such as text, 
boolean, choice (enumerated), command, and window. FormWindow is used to create 
property sheets. 

FormWindowMessageParse provides procedures that parse strings to produce various 
FormWindow types. 

IdieControl provides access to the basic controlling module of ViewPoint. 
KeyboardKey is a client keyboard (the central black keys) registration facility. 
KeyboardWindow provides a particular implementation for a keyboard window. 
Levell VKeys defines the names of the physical keys. 
MenuData allows menus and menu items to be created. 

MessageWindow provides a facility for posting messages to the user in a window. 

PopupMenu allows a menu to be displayed (popped up) anywhere on the screen. 

PropertySheet creates a property sheet. A property sheet is used to show the properties of 
some object to the user and allows the user to change the properties. 

Selection provides the facilities for a client to manipulate the user's current selection. It 
also provides procedures that enable someone other than the originator of the selection to 
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request information relating to the selection and to negotiate for a copy of the selection in 
a particular format. 

SimpleTextDisplay provides facilities for displaying, measuring, and resolving strings of 
Xerox Character Code Standard text. It can handle only non-attributed single-font text. 

SimpleTextEdit provides facilities for presenting short, editable pieces of text to the user. 

SImpleTextFont provides access to the default system font that is used to display 
Viewpoint's text, such as the text in menus, the attention window, window names, 
containers, property sheet text items, and so forth. 

SoftKeys provides for client defined function keys designated to be the isolated row of 
function keys at the top of the physical keyboard. 

StarDesktop provides access to the user's desktop file and window. 

StarWindowShell provides facilities for creating Star-like windows. 

TIP provides basic user input facilities through a flexible mechanism that translates 
hardware level actions from the keyboard and mouse into higher-level client action 
requests. 

TIPStar provides access to ViewPoint's normal set of TIP tables. 

Undo provides facilities that allow an application to register undo opportunities, so that 
when the user requests that something be undone, the application is called to do so. 

Window defines the low-level window management package used by ViewPoint 

XChar defines the basic character type as defined in the Xerox Character Code Standard as 
well as some operations on it. 

XCharSetNNN enumerates the character codes in character set NNN. 

XCharSets enumerates the character sets defined in the Xerox Character Code Standard. 

XComSoftMessage defines messages for some commonly used strings, such as Yes, No, 
day-of-the-week, month, etc. 

XFormat converts various types into XStrings. 

XLReal supports manipulation of real numbers with greater precision than Mesa reals. 

XMessage supports the multinational requirements of systems that require the text 
displayed to the user be separable from the code and algorithms that use it. 

XString provides the basic data structures for representing encoded sequences of 
characters as defined in the Xerox Character Code Standard. It also provides several 
operations on these data structures. 

XTime provides facilities to acquire and edit times into XStrings and XStrings into times, 
XToken parses XStrings into other types 
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4.1 Overview 



ApplicationFolder provides access to the folder that contains all the component files of an 
application. A full application is composed of one or more beds, a message file, a 
description file, and other data files such as .TIP or .Icons. These components are all put 
together into a folder with a specific file type, called an Application (or ApplicationFolder). 

When the application is loaded and started, one of the first things it does is get its data 
files. The actual file names of the data files are specified in the application's description 
file, which is a file that may be read by using the OptionFile interface. The application 
gets its data files by using ApplicationFolder.FromName to obtain the ApplicationFolder file, 
using ApplicationFolder. FindDescriptionFile to get the description file from the 
ApplicationFolder file, and then using OptionFile.GetStringValue to get the data files 
names. (See Usage/Examples.) 



4.2 Interface Items 



FromName: procedure [internalName: xstnng.Reader] 
RETURNS [applicationFolder: NSFiie. Reference]; 

Returns the folder for the given application. internalName is the section name in the 
description file. Returns NSFlle.nullReference if not found. 

FindDescriptionFile: procedure [applicationFolder: NSFiie.Handle] 
RETURNS [descriptionFile: NSFiie.Reference]; 

Finds a file with file type = OptionFile in the applicationFolder. Returns 
NSFlle.nullReference if not found. 

EventData: TYPE = record [ 

applicationFolder: NSFiie.Reference, 
internalName: xstring.Reader]; 

The application loader also notifies the ApplicationLoaded event after loading and 
starting an application. EventData is passed as Event.EventData for this event. 
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4.3 Usage/Examples 

This example code obtains the message file. 

— File: SampleMsgFilelnitlmpLmesa - last edit: 

-- Copyright (C) 1985 by Xerox Corporation. All rights reserved. 
DIRECTORY 

ApplicationFolder using [FindDescriptionFile, FromNameL 
Heap USING [systemZone], 

NSFile USING [Close, Error, GetReference. Handle, nullHandle, nullReference, OpenByName, 

OpenByReference, Reference, Type], 

NSString using [FreeString, String], 

OptionFile using [GetStringValue], 

SampleBWSApplicationOps, 

XMessage using [ClientData, FreeMsgDomainsStorage, Handle, MessagesFromReference, 
MsgDomains], 

XString using [FromSTRING, NSStringFromReader, Reader, ReaderBody]; 

SampleMsgFileimpI: program 

IMPORTS ApplicationFolder, Heap, NSFile, NSString, OptionFile, XMessage, XString 
EXPORTS SampleBWSApplicationOps a { 

-- Data 

h: XMessage.Handle <- nil; 

localZone: uncounted zone Heap.systemZone; 

— Procedures 

OeleteMessages: PROCEDURE [clientData: xMessage.CiientData] = {}; 

GetMessageHandle: public procedure returns [xMessage.Handle] s {returnCH]}; 

InitMessages: procedure = { 

internalName: xstring. ReaderBody ^—xstring. FromSTRING ["SampieBWSApplication"L]; 
msgDomains: XMessage.MsgDomains ^nil; 
msgOomains «- XMessage.MessagesFromReference [ 

file: GetMessageFileRef [AppiicationFoider.FromName [©internalName]], 

clientData: nil, 

proc: DeieteMessages]; 
h <— msgDomains[0]. handle; 

XMessage.FreeMsgDomainsStorage [msgDomains]; 

}; 

GetMessageFileRef: procedure [folder: NSFiie.Reference] 

RETURNS [msgFile: NSFile. Reference <- NSFile. nullReference] a { 
folderHandie: NSFiie.Handle <-NSFiie.OpenByReference [folder]; 
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internalName: xstring.ReaderBody xstring.FromsTRiNG ["SampleBWSAppllcatlon"Ll; 
messageFile: xstring.ReaderBody «-xstring.FromsTRiNG ["MessageFile"L]; 

FindMessageFileFromName: procedure [value: xstring. Reader] s { 

nssName: NSString. String <— xstring. NSStringFromReader [r: value, z: localZonel; 
msgFileHandle: NSFile. Handle <-NSFiie.nullHandle; 

msgFlieHandle <- NSFile.OpenByName [directory: folderHandle, path: nssName ! 

NSFiie.Error = > {msgFileHandle <- NSFile.nullHandle; continue}]; 
IF msgFileHandle a NSFiie.nullHandie then error; — no message file! 
msgFile <-NSFile.GetReference [msgFileHandle]; 
NSFile.Close [msgFileHandle]; 
NSString.FreeString [z: locaiZone, s: nssName]; 

}; 

OptionFiie.GetStringValue [section: ©internal Name, entry: @messageFile, 

callBack: FindMessageFileFromName, 

file: AppikationFolder.FindDescriptionFile [folderHandle]]; 
NSFile.Close [folderHandle]; 

}; 

— Mainline code 
lnitMessages[]; 



Application Folder 



4.4 Index of Interface Items 

Item Page 

EventData: type 1 

FindDescriptionFile: procedure 1 

FromName: procedure 1 
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5.1 Overview 



The Atom interface provides the definitions and proceduresfor creating and manipulating 
atoms. An atom is a one-word datum that has a one-to-one correspondence with a textual 
name. It is often convenient to name an object using a textual name, but XStrings are 
somewhat clumsy to compare and pass around. Using atoms, objects may be named 
textually without paying the expense of actually storing, copying, and comparing the 
strings themselves. Atoms were made popular by the Lisp language. 

The textual name associated with an atom is called its PName, just as it is in Lisp. If two 
atoms are equal, they correspond to the same PName, and vice versa. An atom may also 
have properties associated with it; a property is a [name, value] pair. 



5.2 Interface Items 

5.2.1 Making Atoms 

ATOM: type[1|; 

null: ATOM = loophole[0]. 



An ATOM is a one-word datum that has a one-to-one correspondence with a textual name, 
or PName. If two ATOMs are equal, they correspond to the same PName. If two PNames 
are equal, they correspond to the same ATOM. 

Make: procedure [pName: xstring.Reader] returns [atom: ATOM]; 

MakeAtom: procedure [pName: long string] returns [atom: ATOML- 

MakeAtom and Make return the ATOM corresponding to pName, creating one if 
necessary. In pName, uppercase and lowercase characters are different, and will result in 
different ATOMs. The atom returned is valid for the duration of the boot session, and the 
pName will be remembered for the duration of the boot session. 

GetPName: procedure [atom: ATOM] returns [pName: xstring.Reader]; 
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GetPName returns the name of atom, returning nil if atom is null. It raises the error 
NoSuchAtom if atom is not valid. 1^ 

5.2.2 Error 

NoSuchAtom: error; 

NoSuchAtom may be raised by GetPName, PutProp, GetProp, or RemoveProp. It is raised 
when an operation is presented with an ATOM for which no Make or MakeAtom operation 
has been done in the boot session. Such atoms are called invalid atoms. 

5.2.3 Property Lists 

Pair: TYPE » record (prop: ATOM, value: RefAnyJ; 

RefAny: TYPE = long pointer; 

RefPair: TYPE ■ long pointer to readonly Pair; 

Pair defines the [name, value] pair for a property. Properties are named by atoms and have 
long pointers as values. Property pairs are referenced by a readonly pointer. 

PutProp: procedure [onto: ATOM, pair: Pair]; 

PutProp adds a property pair to onto. If the property already exists, the value is updated. jnfii. 
If onto is null, no action takes place. PutProp will raise the error NoSuchAtom if onto is | 
not valid. 

GetProp: procedure [onto, prop: ATOM] returns (pair: RefPair]; 

GetProp returns the property pair, whose property name is the atom prop, from atom 
onto. If onto does not have a property whose name is prop or onto is null, nil is returned. 
GetProp raises the error NoSuchAtom if onto is not valid. Note: The client may not 
change the property pair. 

RemoveProp: procedure [onto, prop: ATOM]; 

RemoveProp removes the property pair, whose property name is the atom prop, from atom 
onto. If onto is null, no action takes place. RemoveProp raises the error NoSuchAtom if 
onto is not valid. 

5.2.4 Enumerating Atoms and Property Lists 

MapAtomProc: type □« procedure [ATOM] returns [boolean]; 

MapAtomProc is used by MapAtom to enumerate atoms. When it returns true, the 
enumeration stops. 

MapAtoms: procedure (proc: MapAtomProc] returns (lastAtom: ATOM]; 
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MapAtoms enumerates the atoms, calling proc once for each atom. If proc returns true, 
MapAtoms returns that atom. If proc never returns TRUE, MapAtoms returns null. 

MapPListProc: type = procedure [RefPair] returns [boolean]; 

MapPListProc is used by MapPList to enumerate property lists. When it returns true, the 
enumeration stops. Note: The client may not change the property pair. 

MapPList: procedure [atom: ATOM, proc: MapPListProc] returns [lastPair: RefPair]; 

MapPList enumerates the property list of atom, calling proc once for each pair. If proc 
returns TRUE, MapPList returns that pair. If proc never returns true, MapPList returns nil. 



5.2 Usage/Examples 



Two of the major uses of atoms are in the Event and TIP interfaces. In the Event interface, 
atoms name events. In the TIP interface they are used in TIP tables and TIP results to name 
actions. (See those interfaces for more information.) 

The names of atoms are case sensitive. For example, atom1 and atom2 are not equal, 
while atomi and atom3 are equal. 

atom1:ATOM = MakeAtom["Atom"L]; 
atom2: ATOM = MakeAtom["ATOM"L]; 
atom3: ATOM = Mal<e[GetPName[atom1]]; 

The value of an atom is a function of the characters of its name and the names of the atoms 
that have been previously created. Atoms may not be pickled (put in a permanent 
representation that may be filed and recovered later) or transmitted to another system. 
The atom is just a convenient way to represent and manipulate the name, which is the 
permanent representation. 
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5.4 Index of Interface Items 



Item 


Page 


ATOM: TYPE 


1 


GetPName: procedure 


1 


GetProp: procedure 


2 


Make: procedure 


1 


MakeAtom: procedure 


1 


MapAtomProc: type 


2 


MapPList: PROCEDURE 


3 


MapPListProc: type 
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MapAtoms: procedure 


3 


NoSuchAtom: error 


2 


null: ATOM 


1 


Pair: type 
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PutProp: procedure 
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RefAny:TYPE 
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RefPair: type 
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RemoveProp: procedure 
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AtomicProfile 



6.1 Overview 

The AtomicProfile interface provides a general mechanism for storing and retrieving 
global values, such as user name and password. Values are named by atoms and may have 
a type of either boolean, long integer, or string. Only one value isassociated with each 
atom, regardless of type. 

Boolean and long integer values are simple values, unlike string values, which are passed 
by reference. The value of strings may be gotten by calling the GetString routine, in which 
case they must be returned to the implementation using DoneWithString, or they may be 
gotten using a callback procedure in EnumerateString. 

6.2 Interface Items 

6.2.1 Boolean Values 

GetBOOLEAN: procedure [atom: Atom.ATOM] returns [boolean]; 

GetBOOLEAN returns the boolean value associated with atom. If there is no boolean value 
associated with atom, GetBOOLEAN returns false. 

SetBOOLEAN: procedure [atom: Atom.ATOM, boolean: boolean]; 

SetBOOLEAN associates the boolean value boolean with atom. If atom previously had 
another value associated with it, that value is replaced. The event AtomicProfileChange is 
notified, with event data being a long pointer to atom. 

6.2.2 Integer Values 

GetLONGINTEGER: procedure [atom: Atom.ATOiM] returns [long integer]; 

GetLONGINTEGER returns the long integer value associated with atom. If there is no long 
integer value associated with atom, GetLONGINTEGER returns 0. 
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SetLONGINTEGER: procedure [atom: Atom.ATOM, int: long integer ]; 

SetLONGINTEGER associates the long integer value int with atom. If atom previously had 
another value associated with it, that value is replaced. The event AtomicProfileChange isi 
notified, with event data being a long pointer to atom. 



6.2.3 String Values 

GetString: procedure [atom: Atom.ATOM] returns [ xstring.Reader]; 

GetString returns the string value associated with atom. The string is reference counted, 
and the client must return the string by calling DoneWithString. If there is no string 
value associated with atom, GetString returns nil. 

DoneWithString: procedure [string: xstring.Reader]; 



After obtaining a reader using GetString, it must be returned via DoneWithString so the 
implementation's use-count will be correct. Failure to do so will result in a storage leak if 
the value of the atom is replaced (see the example below). 

EnumerateString: procedure [ 

atom: Atom.ATOM, proc: procedure [xstring.Reader]]; 

EnumerateString provides an alternate method of examining the string value of an atom. 
If atom has a string value, proc will be called with the string value, proc is called from 
within the monitor if the implementation. The reader is valid for the duration of the 
callback, but proc must not call any of the operations in the implementation. If atom has 
no string value, proc will not be called. 

SetString: procedure [atom: Atom.ATOM, string: xstring.Reader, 
immutable: boolean <- false ]; 



SetString associates the string value string with atom. If atom previously had another 
value associated with it, that value is replaced. If immutable is false, SetString will copy 
string's body and byte sequence, otherwise it only copies the reader body. The client must 
not deallocate the byte sequence in this case. The event AtomicProfileChange is notified 
with event data being a long pointer to atom. 



6.3 Usage/Examples 

AtomicProfile provides a general mechanism for storing and retrieving values. Actual use 
by a client depends on knowing the names and expected types of values. ViewPoint defines 
some basic values such as user name and password. Other systems may define other 
values. 



The following example has a client keeping track of the user name, which depends on the 
AtomicProfileChange event. UserNameChanged is called when any AtomicProfile value is 
changed. By examining the event data of the agent procedure, the example can act on 
changes to the user name. 
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atomlcProfileChange: Atom ATOM = Atom.MakeAtom("AtomicProfileChange"L]; 
fullUserName: Atom.ATOM = Atom.MakeAtom["'FullUserName"L]; 
debugging: Atom.ATOM = Atom.MakeAtom["Debugging"L]; 

UserNameChanged: EventAgentProc = { 

atomChanged: LONG POINTER TO Atom.ATOM s eventData; 
iFatomChanged I = fullUserName then { 
name: xstring.Reader a GetString[fullUserName]; 
< < do processing of new name > > 

IF GetBOOLEAN[debugging] then { < < do debugging only code > > }; 
DoneWithString[name]}}; 

Event.AddOependency[ 

agent: UserNameChanged, myData: nil, event: atomicProfileChange]; 
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6.4 Index of Interface Items 



Item Page 

DoneWithString: PROCEDURE 2 

EnumerateString: PROCEDURE 2 

GetBOOLEAN: PROCEDURE 1 

GetLONGINTEGER: procedure 1 

GetString: PROCEDURE 2 

SetBOOLEAN: procedure 1 

SetLONGINTEGER: procedure 2 

SetString: procedure 2 
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7.1 Overview 

The Attention interface provides a means of displaying messages to the user. It 
implements a single window into which messages are displayed. In addition to displaying 
messages, the Attention window has a menu to which clients can add system-wide 
commands. 

There are three types of messages: simple messages, sticky messages, and confirmed 
messages. Simple messages have no special semantics. Sticky messages are redisplayed 
when a non-sticky message is cleared. Attention keeps track of one sticky message. 
Confirmed messages ask for confirmation by the user. 

Attention allows messages to be logically appended. Each of the posting operations, Post, 
PostSticky, and PostAndConfirm, contain a boolean parameter clear. If dear is true, the 
window is cleared before the message is displayed. If not, the message is appended to the 
currently displayed message. This allows the client to use Attention to construct complex 
messages. 

The single global Attention window and construction of messages does not work well if 
multiple processes try to display messages simultaneously. To work around this conflict, 
the following restriction is imposed: The Attention interface may only be called from the 
notifier process. If another process wishes to post a message in the Attention window, it 
should use the periodic notification mechanism provided by the TIP interface. Following 
this rule guarantees that only well-formed messages will be displayed. 

To facilitate construction of messages, an XFormat.Handle is provided whose format 
procedure will post a simple message without clearing the window. See the example below 
and the XFormat chapter for more information. 

The Attentton window has a global system menu. Operations are provided so clients may 
add menu items to this menu, remove items from the menu, or swap items in the menu. 
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7.2 Interface Items j 

7.2.1 Simple Messages 

Post: PROCEDURE [s: xstring.Reader, clear: boolean <-true, beep: boolean <- false, 
blink: boolean false] ; 

Post displays the message s in the Attention window. If clear is TRUE, it clears the 
Attention window before displaying s; otherwise, it displays it after whatever text is 
currently showing. Attention makes its own copy of the reader body and bytes of s. beep 
and blink stipulate that the corresponding feedback be presented to the user. 

Clear: procedure; 

Clear clears the Attention window of any simple message. If a simple message is being 
displayed and there is a current sticky message, the sticky message will be displayed. 
Clear has no effect if a sticky message is being displayed. 

formatHandle: XFormat.Handle; 

formatHandle is an XFormat.Handle provided by the Attention window that clients can use 
to post simple messages. Its format procedure logically calls Post with clear being false. 
(See below for an example.) 

7.2.2 Sticky Messages | 

Sticky messages are redisplayed when a non-sticky message is cleared. Attention keeps 
track of one sticky message. 

PostSticky: procedure [s: xstring.Reader, clear: boolean <-true1, 
beep: boolean false, blink: boolean <- false; 

PostSticky appends s to, or replaces, the current sticky message, and then displays this 
new message in the window. Its operation is: (1) if the window has a simple message or 
clear, then clear the window; (2) if clear, then clear the current sticky message; (3) append 
s to the current sticky message; and (4) display the new current sticky message. Attention 
makes its own copy of the reader body and bytes of s. beep and blink are the same as in 
Post above. 

ClearSticky: procedure; 

ClearSticky clears any current sticky message. If a sticky message is being displayed, the 
window is cleared. ClearSticky has no effect if there is no sticky message. 

7.2.3 Confirmation Messages 

PostAndConfirm: procedure [ 

s: xstring.Reader, clear: boolean <- true, confirmChoices: ConfirmChoices ^[nil, nil], ^i*P*|^ 
timeout: Process.Ticks <-dontTimeout, 
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beep: boolean <- false, blink: boolean <- false] 
RETURNS [confirmed, timedOut: boolean]; 

ConfirmChoices: type = record [yes, no: xstring.Reader]; 

donf rimeout: Process.Ticks = 0; 

PostAndConfirm acts like Post in displaying the message s but waits for confirmation by 
the user. The confirmChoices messages are displayed, and the user should select one of the 
choices with the mouse. If the user selects yes, confirmed is returned true; if no is selected 
or the STOP key is depressed, confirmed is returned false. If confirmChoices. yes # NIL and 
confrmChoices.no = NIL, then only confirmChoices. yes is posted and confirmChoices.no 
is ignored. This is useful for posting a message that the user must see, but for which the 
user gets no choice, such as "Unable to communicate with the printer: CONTINUE". 
PostAndConfirm absorbs all user input except the STOP key and mouse actions over the yes 
and no messages. The client may specify a timeout value, which will cause 
PostAndConfirm to return confirmed false and timedOut true if the user does not act 
within timeout ticks. The default value dontTimeout disables this timeout feature. 
Attention makes its own copy of the reader body and bytes of s. 

7.2.4 System Menu 

AddMenultem: procedure [item: MenuData.ltemHandle]; 
AddMenultem adds item to the global system menu. 
RemoveMenultem: procedure [item: MenuData.ltemHandle]; 

RemoveMenultem removes item from the global system menu. There is no effect if item is 
not in the menu. 

SwapMenultem: procedure [old, new: MenuData.ltemHandle]; 

SwapMenultem swaps new for old in the global system menu. SwapMenultem[old: nil, 
new: item] is equivalent to AddMenultem[item: item] and SwapMenultem[old: item, 
new: nil] is equivalent to RemoveMenultem[item: item]. 

7.3 Usage/Examples 

The following example has a client displaying the name and size of a file. It uses the NSFile 
interface to access the file and get the name and size attributes. See the Services 
Programmer's Guide (610E00180): Filing Programmer s Manual for documentation on the 
NSFile interface. 

PostNameAndSize: procedure [file: NSFiie.Handie] 38 { 

nameSelections: NSFiie.Selections a [interpreted: [name; true]]; 

attributes: NSFile.AttributesRecord; 

rb: xstring.ReaderBody «~ Message[theFile]; 

Attention.Post[s: @rb, clear: true]; -- start a new message 

XFormat.NSString[Attention.formatHandle, attributes. name]; 

xFormat.ReaderBody[h: Attention.formatHandle, rb: Message[contains]]; 

XFormat.Decimal[h: Attention.formatHandle, n: NSFiie.GetSizelnBytes[file]l; 
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rb <f- Message[bytes]; 

Attention.Post[s: @rb]}; -- clear defaults to false 

Message: procedure [key: {theFile, contains, bytes}] returns [xstring.ReaderBody] s { 
...}; 

An example of the resulting message displayed in the Attention window is 

The file Foo contains 53324 bytes 

The example intermixes use of the format handle and use of the Post procedure. A client 
could clear first, using the Clear procedure, and then display the message just using the 
format handle. 
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7.4 Index of Interface Items 



Item 


Page 


AddMenultem: procedure 


3 


Clear: procedure 


2 


ClearSticky: procedure 


2 


ConfirmCholces: type 


3 


dontTimeout: Process.Ticks 


3 


formatHandle: XFormat.Handle 


2 


Post: procedure 


2 


PostAndConfirm: procedure 


2 


PostSticky: procedure 


2 


RemoveMenultem: procedure 


3 


SwapMenultem: procedure 


3 
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8.1 Overview 



The BlackKeys interface provides the capability to change the interpretation of the main 
(central) section of the physical keyboard. Included are the data structures that define a 
keyboard record, as well as the procedures used to manipulate the keyboard stack. 

The average client will use only the data structures that are provided by the BlackKeys 
interface. The procedures are reserved for a keyboard manager interested in interfacing 
between the user and the blackkeys stack of keyboards. 



8.2 Interface Items 

8.2.1 Keyboard Data Structures 



The BlackKeys data structures provide the framework for client-defined keys in the main 
(central) section of the physical keyboard. This includes interface to a keyboard picture 
whose keytops may be selected with the mouse to simulate pressing of the physical key on 
the keyboard. 

Keyboard: TYPE = long pointer to KeyboardObject «-nil; 

KeyboardObject: type = record [ 
table: Tip.Table 4-nil, 

charTranslator: TiP.CharTranslator <-[proc; nil. data: nil], 
pictureProc: PictureProc <-nil, 
label: xstring.ReaderBody «- xstring.nuiiReaderBody, 
clientData: long pointer <«- nil]; 

KeyboardObject is the keyboard interpretation data structure. The client may provide its 
own TiP.Table or default it to nil, in which case the NormalKeyboard.TIP table is used. (See 
Appendix A for productions returned by NormalKeyboard.TIP.) A TiP.CharTranslator may be 
provided to handle char and bufferedchar productions from a tip. Table. A PictureProc may 
be provided to be called when installing or removing this keyboard. Absence of such a 
procedure assumes there is not a picture associated with this keyboard, label is the string 
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that will appear in the SoftKeys window when the KEYBOARD key is pressed down. 
Pressing (or mousing) the key marked label will invoke this keyboard. clientOata is 
provided to associate any other information the client might need to keep with the 
keyboard. 

PictureProc: type = procedure [ 
keyboard: Keyboard, 
action: PictureAction] 

RETURNS [ 

picture: Picture *- nullPicture, 
geometry: GeometryTable <-nil]; 

PictureProc is a client-provided procedure that will be called by a keyboard window 
application when the client's keyboard is being installed (action = acquire) or removed 
(action = release) from the top of the blackkeys stack of active keyboards. The client may 
use this opportunity to map or unmap the picture and geometry table used by the 
keyboard window application. 

PictureAction: type = (acquire, release}; 

acquire = client's keyboard is being installed at the top of the keyboard stack 
(becoming the current keyboard) 

release « client's keyboard is being removed from the top of the keyboard stack 
PictureType: type = {bitmap, text}; 

Picture: TYPE = RECORD [ 

variant: select type: PictureType from 
bitmap = > [bitmap: long pointer], 
text = > [text: xstring. Reader] 
endcase]; 

The variant of the record, Picture, allows the client the choice of presenting his keyboard 
window in either bitmap or textual form. (See the KeyboardWindow interface for 
discussion of the structure behind a keyboard bitmap.) text is pointed to by an 
xstring.Reader. The text will not be copied. 

nullPicture: bitmap BiackKeys.Picture= [bitmap[NiL]]; 

The variable nullPicture represents a null entry to the keyboard window. 
GeometryTable: TYPE = long pointer,- 

A geometry table allows access to the data structure. (See the KeyboardWindow interface 
chapter for discussion of the structure of a geometry table.) 

8.2.2 Getting a Handle to the Current Keyboard 

BlackKeysChange: Event.EventType; ATOM defined as "BlackKeysChange" 
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Changing the keyboard at the top of the blackkeys stack of keyboards will result in the 
notification BlackKeysChange through the Event mechanism. The eventData supplied by 
the Event.Notify will be the current keyboard handle. 

GetCurrentKeyboardI: procedure returns [current: Keyboard]; 

GetCurrentKeyboard returns the current keyboard from the top of the blackkeys stack. 

8.2.3 Procedures 

Push: PROCEDURE [keyboard: Keyboard]; 

The Push procedure installs a black key interpretation at the top of the blackkeys stack of 
keyboards. The TiP.Table an<i/or TiP.CharTranslator will be registered with tip and the event 
BlackKeysChange will be broadcast. 

Remove: PROCEDURE [keyboard: Keyboard]; 

The Remove procedure removes the keyboard from the stack of active keyboards and 
resets the TiP.Table and TiP.CharTranslator as applicable. The event BlackKeysChange will 
be broadcast if keyboard is on the top of the blackkeys stack. 

May raise the ERROR BlackKeys.lnvalidHandle. 

Swap: PROCEDURE [old: Keyboard, new: Keyboard]; 

The Swap procedure is designed to change black keys' interpretations without returning 
to some previous or other default value in between. It is essentially the equivalent of a 
Remove followed by a Push. The event BlackKeysChange will be broadcast if the keyboard 
being removed was on top of the stack. 

May raise the error BlackKeys.lnvalidHandle. 

8.2.4 Errors 

InvalidHandle: error: 

This error is raised if the keyboard passed to Remove or Swap (old) is not in the set of 
active BlackKeys keyboards. 

8.3 Usage/Examples 

8.3.1 Defining a Keyboard Record 

OefineKey board: procedure = 

BEGIN 

nameString: xstring.ReaderBody xstring.FromSTRINGl"Swahili"Li 

swahiilKeyboardRecord: BiackKeys.KeyboardObject <-[ 
table: NIL, 

charTranslator: [MakeChar, nil]. 
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pictureProc: MapBitmapFile, 

label: xstring.CopyToNewReaderBody[@nameString, Heap.systemZone]]: 
save the pointer to the record somewhere for future use — 
END; --Oef/neKeyboard -- 

MapBitmapFile: BiackKeys.PictureProc = 

BEGIN 

pixPtr: BlackKeys.Picture.bitmap ♦-BlackKeys.nullPicture; 
SELECT action from 
acquire = > 

[--Do the right thing to map the bitmap. Uses the default geometry table. — 
RETURN(pixPtr, KeyboardWindow.defaultGeometry] }; 
release = > [—Do the right thing to unmap the bitmap — 

RETURN(BlackKeys.nullPicture, NIL] } 

END; — MapBitmapFile 
MakeChar: Tip.KeyToCharProc = 

BEGIN 

—map bufferedChar to desired xstring.Character — 
END; - MakeChar 
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8.4 Index of Interface Items 



Item Page 

BlackKeysChange: Event.EventType 2 

Geometry Table: type 2 

GetCurrentKeyboard: PROCEDURE 3 

InvaiidHandle: error 3 

Keyboard: TYPE 1 

KeyboardObject: type 1 

nullPictureibitmap Picture 2 

Picture: type 2 

PictureAction:TYPE 2 

PictureProc: type 2 

PictureType: type 2 

Push: procedure 3 

Remove: procedure 3 

Swap: procedure 3 




8-5 



8 



BlackKeys 



8-6 



BWSAttributeTypes 



9.1 Overview 

BWSAttributeTypes defines the NSFile. Extended AttributeTy pes that are used by 
Viewpoint and defines the first NSFile. Extended AttributeType available for client use. 

The only extended attributes defined here are the ones that can be attached to any file, 
such as mailing and filing application attributes. Attributes that are unique to a 
particular application's files should be defined privately within that application rather 
than defined here. It is acceptable for several applications to use the same extended 
attributes because application A should never be reading the attributes from application 

B*S files and vice versa. F'ine Point: Several application-specific attribute types are included in this 
interface for compatibility. 

Here we define the extended attributes that can be attached to any file, leaving a few 
spare ones for future use. We also define the first available "application attribute" 
(firstAvailableApplicationType). Caution: No application should use an extended 
attribute smaller than this one! Nor should an application use an extended attribute 
larger than lastBWSType. 

9.2 Interface Items 



9.2.1 Available Application Types 

firstAvailableApplicationType: NSFiie. Extended AttributeType * . . . ; 
lastBWSType.' NSFile„ Extended AttributeType = . . . ; 

Applications should only use the types in the range [firstAvailableApplicationType . . 
lastBWSType). firstAvailableApplicationType is the first extended attribute type that 
applications can use to store application-specific attributes. Caution; No application 
should use an extended attribute smaller than firstAvailableApplicationType. 
lastBWSType is the last extended attribute type that applications can use to store 
application-specific attributes. Caution: No application should use an extended attribute 
larger than lastBWSType. 
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If a Viewpoint client needs more attributes than the number in this range, the client 
should see the NSFiling group to obtain a range specific to that client. 

9.2.2 Viewpoint Types 

Please consult the Mesa interface for the exact assignment of ViewPoint-specific types. 
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Item Page 

firstAvailableApplicationType: NSFiie.ExtendedAttributeType 1 
lastBWSType: NSFiie.ExtendedAttributeType 1 
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10,1 Overview 



BWSFileTypes defines several NSFile.Types used by ViewPoint. These types should not be 
used by applications. (Also see the Catalog and Prototype interfaces.) 

All file types used by ViewPoint clients must be managed by the client. Ranges of file 
types may be obtained from the Filing group. 



10.2 Interface Items 

root: NSFile.Type 



The root file of the volume has this type. The root has children that are called (by 
convention) catalogs, 

desktop, desktopCatalog: NSFile.Type s . . . ; 

The desktop catalog contains all the desktops on a workstation. An individual desktop has 
the same type as the desktop catalog. 

prototypeCatalog: NSFile.Type = . . ; 

The prototype catalog contains prototype files for each application. A prototype file is a 
blank application file that the user can make copies of, such as Blank Folder, Blank 
Document. (See the Prototype interface.) 

systemFlleCatalog: NSFile.Type a . . . ; 

The system file catalog contains system files, such as the beds for an application, message 
files, font files, TIP files, etc. (See the Catalog interface.) 
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10.3 Index of Interface Items 

Item Page 

desktop: NSFiie.Type 1 

desktopCatalog: NSFiie.Type 1 

prototy peCata log:NSFiie.Type 1 

root: NSFiie.Type 1 

system FileCata log: NSFiie.Type 1 
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11.1 Overview 

BWSZone defines several zones, each with different characteristics, that may be used by 
Viewpoint clients as appropriate. 

11.2 Interface Items 

All these zoiles are created at boot time and exist for the duration of the boot session. 

permanent: UNCOUNTED zone; 

Permanent: procedure returns [uncounted zone]; 

permanent is intended for nodes that are never deallocated. It has infinite threshold. 
Permanent returns permanent. 

logonSession: UNCOUNTED zone; 

LogonSession: procedure returns [uncounted zone] ; 

logonSession is intended for nodes that last for a logon/logoff session. logonSession is 
emptied of all nodes at each logoff (i.e., Heap.Flush). LogonSession returns logonSession. 
logonSession is created at boot time, and is flushed at logoff. 

shorttifetime: uncounted zone; 

ShortLifetime: procedure returns [uncounted zone]; 

shorttifetime is intended for nodes that are allocated for a very short time, such as during 
a notification, ShortLifetime returns shortLifetime. 

semipermanent: uncounted zone; 

Semipermanent: procedure returns [uncounted zone]; 

semipermanent is intended for nodes that are allocated for a very long time but that might 
occasionally have to be expanded. Semipermanent returns semipermanent. 

Ill 
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11.3 Index of Interface Items 

Item Page 

LogonSession: procedure 1 

logonSession: UNCOUNTED ZONE 1 

Permanent: procedure 1 

permanent: UNCOUNTED ZONE 1 

Semipermanent: procedure 1 

semipermanent: UNCOUNTED ZONE 1 

ShortLifetime: procedure 1 

shortLifeti me: UNCOUNTED ZONE 1 
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12.1 Overview 

Catalog manipulates files that are direct descendants of the root file on a NSFiling 
volume. These files are referred to as catalogs. Each catalog is uniquely identified by its 
file type. Files can be opened and created within a catalog. Catalogs can be opened, 
created, and enumerated. 

Viewpoint creates a system file catalog and a prototype catalog (see the Prototype 
interface) at boot time. The system file catalog typically holds font files, TIP files, icon 
picture files, message files, etc. 

12.2 Interface Items 

12.2.1 Finding and Creating Files in a Catalog 

GetFile: procedure [ 

catalogType: NSFiie.Type <-BWSFiieTypes.systemFileCatalog, 

name: xstring.Reader, 

readonly: boolean*- false, 

session: NSFiie.Session <~NSFiie.nullSession] 

RETURNS [file: NSFiie. Handle]; 

GetFile finds a file with name name in the catalog with type catalogType. If the file cannot 
be found, NSFiie. nullHandle is returned. 

CreateFile: procedure [ 

catalogType: NSFiie.Type ^-BWSFiieTypes.systemFlleCatalog, 

name: xstring. Reader, 

type: NSFile.Type, 

isDirectory: boolean «- false, 

size: long cardinal <- 0, 

session: NSFiie.Session <~NSFiie.nullSession] 

RETURNS [file: NSFiie.Handle]; 
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CreateFile creates a file with the specified attributes (name, type, isDirectory, size in 
bytes) in the catalog with type catalogType. 

12.2.2 Operating on Catalogs 

Open: procedure ( 

catalogType: NSFiie.Type, 

session: NSFiie.Session <-NSFiie.nullSession] 

RETURNS [catalog: NSFiie.Handle]; 

Opens the catalog with type catalogType. If the catalog cannot be opened, 
NSFile.nullHandle is returned. 

Create: procedure [ 

name: xstring. Reader, 

catalogType: NSFiie.Type, 

session: NSFiie.Session ^NSFiie.nuilSession] 

RETURNS [catalog: NSFiie.Reference]; 

Creates a catalog with the specified name and type. If the catalog already exists or cannot 
be created, NSFile.nullReference is returned. Note: Even though the file can be identified by 
type only, the name should be logical (e.g., "System Files") so that any tools written to 
manipulate catalogs can display these names. 

Enumerate: procedure [proc: CatalogProc]; 

CatalogProc: type s procedure [catalogType: NSFiie.Type] 
RETURNS [continue: boolean*- true]; 

Enumerate calls the client supplied proc for each existing catalog or until proc returns 

FALSE. 

bef oreLogonSession : NSFiie.Session; 

beforeLogonSession is a session that can be used when calling a Catalog procedure before 
any user has logged on, such as at boot time. It is set to be the default session until a user 
logs on. 
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12.3 Index of Interface Items 



Item Page 

beforeLogonSession: NSFiie.Session 2 

CatalogProc: type 2 

Create: procedure 2 

CreateFile: procedure 1 

Enumerate: procedure 2 

GetFile: procedure 1 

Open: procedure 3 
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13.1 Overview 

Containee is an application registration facility. An application is a software package that 
implements the manipulation of one type of file. Containee is a facility for associating an 
application with a file type. 



13.1.1 Background 

All NSFiles have: 

• a name 

• a file type (long cardinal) 

• a set of attributes, such as create date 

• either: 

• content, such as a document 

• children that are also NSFiles, such as a folder 



An NSFile that has children is often called a directory. Fine Point: An NSFile can actually have 
both content and children, that i.'5 ignored for now to simplify this discussion. Since the children of an 
NSFile can themselves have children, NSFile supports a hierarchical file system. 

A ViewPoint desktop is backed by an NSFile that has children. Each child file of the 
desktop's NSFile is represented on the screen by an iconic picture. 

Each application operates on NSFiles of a particular file type. For example, ViewPoint 
documents operate on NSFiles with file type of 4353. Each document icon is actually an 
NSFile of type 4353. Each application needs a way to register its ability to operate on files 
of a particular type. Containee is such a facility. 

13.1.2 Containee.Implementation 

^taf^ An application's ability to operate on files of a particular type includes such operations as: 
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• Display of the iconic picture (full size and tiny). j 

• Open, performed when the user selects an icon and presses OPEN. 

• Properties, performed when the user selects an icon and presses PROPS. 

• Take the current selection, performed when the user drops an object onto an icon 
by copying or MOVEing a selected object to an icon. 

An application registers itself by calling Containee. Setlmplementation, supplying a file 
type and a Containee.lmplementation. A Containee.lmplementation is a record that contains 
two important procedures: 

• A procedure for displaying an icon picture (Containee. PictureProc). 

• A procedure for performing various operations on an icon, such as open, create a 
property sheet, and take the current selection (Containee. GenericProc). 

This application registration allows the ViewPoint desktop implementation to be open- 
ended. The desktop implementation itself does not know how any file behaves. Rather it 
depends on applications registering their ability to operate on particular file types. The 
desktop implementation, at logon, simply enumerates the child files of the desktop's 
NSFile (using NSFIIe.List), obtaining the file type for each child. For each child file, the 
desktop implementation gets an application's Containee.lmplementation by using the child 
file's file type (and Containee.Getlmplementation) and then calls that application's 
Containee. PictureProc to actually display an icon picture. Similarly, when the user selects 
an icon on the desktop and presses OPEN, the desktop implementation uses the file type of ^.iiiitii, 
the file at that place on the desktop to get the application's Containee.lmplementation and | 
then calls the application's Containee. GenericProc to get a StarWindowShell created. The 
implementations of Folders and File Drawers are similar to the desktop implementation 
in this respect. 

13.1.3 Containee.Oata 

An application needs to distinguish one file from another. Two different documents may 
be the same file type, but probably have different names and different contents. Whenever 
an application's Containee. DispiayProc or Containee. GenericProc is called, the particular file 
being operated on by the user is passed to the procedure through the Containee. DataHandle 
parameter. A Containee.DataHandle is a pointer to a Containee.Oata that is simply a record 
with an NSFile.Reference in it. An NSFile.Reference uniquely identifies a particular file and 
allows the application to utilize various NSFile file-accessing procedures for manipulating 
the file. 

13.2 Interface Items 

13.2.1 Items for Application Implementors 

Setlmplementation: procedure [NSFiie.Type, Implementation] 
RETURNS [ Implementation]; 

Setlmplementation associates an Implementation record with a particular file type and I 
returns the previous Implementation that was associated with that file type. An 
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application calls Setlmplementation to register its ability to operate on files of a 
particular type. • 

Implementation: TYPE » record [ 
implementors: long pointer <- nil, 
name: xstring.ReaderBody <-xstring.nullReaderBocly, 
smallPictureProc: SmallPictureProc <-nil, 
pictureProc:PictureProc ^ nil, 
convertProc: Selection.ConvertProc <- nil, 
genericProc:GenericProc <-NiL ]; 

When an application registers its ability to operate on files of a particular type (i.e, calls 
Setlmplementation), it supplies an Implementation record. The Implementation record 
defines the behavior of all files of that type. 

implementors is provided for the convenience of clients that may want to associate some 
application-specific data with the Implementation record. Note: This data is one per 
application, not one per file. 

name is a user-sensible name for the objects that the Implementation manipulates, such 
as "Document" or "Spreadsheet." This string typically comes from XMessage. The bytes of 
name are not copied—the storage for name must be allocated forever (which is easy to do 
using XMessage). 

smallPictureProc is a procedure of type SmallPictureProc that returns a character. This 
procedure is describe below. 

pictureProc is called whenever the file's full-sized icon picture needs to be painted. (See 
PictureProc.) 

convertProc is called to convert the file into another form, such as an Interpress master. 
This procedure is used when the owner of the current selection is a container, such as a 
folder, and the selection is actually a file (row) in the container. The owner of the selection 
(i.e., the container implementation) may be called to convert the selected file (row), but 
only the application that implements that file's type can do the conversion. The 
convertProc allows the owner of the selection to pass the conversion request along to the 
application. The data parameter to the convertProc is a containee.DataHandle. This 
convertProc does not need to be able to convert to a target type of file or fileType, but 
rather should call Containee.OefaultFileConvertProc for these target types. If the 
application does not perform conversion to any target types, 
Contamee.DefauitFileConvertProc should be provided as the convertProc. 

genericProc is where most of the application's real implementation resides. genericProc is 
called, for example, to open an icon, to produce a property sheet for an icon, to drop 
something on an icon, etc. See GenericProc. 

SmallPictureProc: type = procedure [ 
data: DataHandle <-nil, 
type: NSFiie.Type ignoreType, 
normalOrReference: PictureState] 
RETURNS [smallPicture: xstring.Character]; 

PictureState: type = { garbage, normal, highlighted, ghost, 
reference, referenceHighlighted }; 
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ignoreType: NSFile.Type = last[long cardinal] ; 

The SmallPictureProc should return a character for the application, which should be 
obtained by passing a 13x1 3-bit icon picture to SimpleTextFont.AddClientDefinedCharacter 
This character is used when the file is inside a folder. normalOrReference will be either 
normal or reference, and the appropriate small picture should be returned. The 
SmallPictureProc should try to use the type parameter first if it is not 
Containee. ignoreType. If it is ignoreType, the SmallPictureProc should use the data 
parameter. This change is necessary for allowing the reference icon application to work: 

properly. Fine Point: The picture for normalOrReference = reference/referenceHighlighted will not 
normally be used by the folder application directly, but rather would be used by a generic reference iconi 
application. 

Data: type ■ record [ 

reference: NSFile.Reference <-NSFiie.nullReference ]; 

DataHandle: TYPE = longpointerto Data; 
nullOata:Oata; 

Data uniquely identifies a file. An application needs to distinguish one file from another. 
Two documents may be the same file type, but probably have different names and 
different contents. Whenever an application's PictureProc or GenericProc or 
Implementation.convertProc is called, the particular file being operated on by the user is 
passed to the procedure through the DataHandle parameter. An NSFile.Reference uniquely 
identifies a particular file and allows the application to utilize various NSFile file- 
accessing procedures for manipulating the file, null Data is a constant that should be used 
to represent a null Containee. Data. 

GenericProc: type a procedure ( 

atom: Atom.ATOM, 

data:DataHandle, 
changeProc:ChangeProc if-NiL, 
changeProcData: long pointer <- nil] 

RETURNS [long UNSPECIFIED]; 

A GenericProc is a procedure supplied by an application as part of an Implementation. The 
GenericProc will be called to perform one of several operations that a user can invoke, 
atom tells the GenericProc what operation to perform. For example, when the user selects 
an icon and presses the OPEN key, the application's GenericProc is called with an atom of 
Open. 

data identifies the particular NSFile to be operated on. The NSFile's file type will be the one 
for which this application has registered its Implementation. 

A GenericProc must return a value. The type of the return value depends on the atom 
passed in. Some atoms, their meaning to the GenericProc, and the expected return values 
are as follows: 

Atom Return Value and Meaning 

CanYouTakeSelection long pointer to boolean 

If the application is willing to have the current selection 
dropped onto it, the GenericProc should return true. This 



ViewPoint Programmer's Manual 



13 



Open 



Props 



TakeSelection 



TakeSelectionCopy 



occurswhen the user has selected something, pressed COPY or 
MOVE, and then selected one of this application's files. While 
the user has the mouse button down, the cursor changes to a 
question mark if the GenericProc returns false; otherwise, the 
cursor stays the same and the icon picture flashes. This 
operation should be efficient and usually involves calling 
Selection.CanYouConvert or Selection. HowHard or Selection. Query 
to determine what Selection. Targets the selected object can be 
converted to. For example, the printing application's 
GenericProc returns true if the current selection can be 
converted to an Interpress Master. 

StarWindowShell.Handie 

The application should create a StarWindowShell. Usually, 
the content displayed in the StarWindowShell will be derived 
from the contents of the file. For example, the ViewPoint 
document editor application displays the text and graphics 
contained in the file, thus making the file ready for viewing 
and/or editing. 

StarWindowShell.Handie 

The application should create a PropertySheet. Usually, the 
properties shown reflect some attributes of the file. For 
example, the Folder property sheet shows the name of the 
folder, how it is sorted, and how many objects it contains. 
These properties are all NSFile attributes of the file. 

LONG POINTER TO BOOLEAN 

The action performed for this atom is highly dependent on the 
particular application. This atom is passed when the user has 
selected something, pressed MOVE, then selected one of this 
application's files. For some applications, this means the 
selected object should be moved into this application; for 
example, the Folder application converts the selected object to 
a file and adds the file to the folder. For other applications, this 
means the selected object should be operated on in some 
application-specific fashion; for example, the printing 
application converts the selected object to an Interpress Master 
(file or stream) and then sends the master to a printer. The 
GenericProc should return true if the operation was successful, 
FALSE otherwise. 

LONG POINTER TO BOOLEAN 

This atom has the same meaning as TakeSelection, except it 
corresponds to the COPY key being pressed rather than MOVE. 
Again, the meaning of this is highly application dependent. 



If the execution of the GenericProc causes any change to the NSFile's attributes, the 
changeProc should be called. This allows containers (such as Desktop, Folders) to update 
the display to reflect the changes. For example, when the atom is Props, the GenericProc 
must save the changeProc and return the StarWindowShell.Handie for the property sheet. 
Then later, if the user changes the file's name, for example, the application's 
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FormWindow.MenuitemProc gets control when the user is done and must then retrieve the jgm^ 
changeProc and call it. (See the section on Usage/Examples for more detail.) | ' 

If the client's GenericProc is called with an atom that it does not recognize, it should call 
the previous GenericProc (using the old Implementation that was returned when it called 
Containee. Setlmplementation). The original system-supplied GenericProc acts to backstop 
all possible atoms. 

ChangeProc: type = procedure [ 

changeProcData: long pointers- nil, 
data:DataHandle, 

changed Attributes: NSFiie. Selections «- [] 
noChanges: boolean false] ; 

A ChangeProc is a callback procedure that is passed to a GenericProc. It must always be 
called by the client regardless of whether an attribute of the file being operated has 
changed. The reason for always calling the changeProc is to allow deallocation of the 
changeProcOata. The noChanges boolean indicates the effect on the relevant file's 
attributes. The changeProcData parameter must be correctly supplied even for the 
noChanges = true case. This is used, for example, when the user changes the name of a 
file by using a property sheet. When the property sheet is taken down, the application 
changes the file's name and the ChangeProc that was passed to the GenericProc must then 
be called by the application. (See more detail in the section on Usage/Examples). 

PictureProc: type * procedure [ 
data:DataHandle, 

window: window.Handle, I 

box: Window. Box, 

old, new: PictureState]; 

PictureState: type = (garbage, normal, highlighted, ghost, reference, referenceHighlighted}; 

A PictureProc is a procedure supplied by an application as part of an Implementation. The 
PictureProc is called whenever the desktop implementation needs to have the application's 
icon picture repainted or painted differently. 

data identifies the particular NSFiie whose picture should be painted. The NSFIIe's file type 
will be the one for which this application has registered its Implementation. Even though 
all files of the same type will have the same PictureProc and therefore the same-shaped 
picture, each picture will differ because the name of the NSFiie is often displayed on the 
picture. An application's PictureProc can obtain an NSFile's name by using NSFiie 
operations, but may more easily obtain it using Containee.GetCachedName. This is one of 
the primary intended uses for GetCachedName. (See the section on Attribute Cache). 

window and box should be passed to any display procedures used to paint the icon picture, 
such as Oisplay.Bitmap and SimpleTextDisplay.StringlntoWindow. 

The old and new arguments describe the current and desired states of the icon picture, 
garbage is the unknown state. PictureProc will be called with news garbage before 
moving or otherwise altering the icon; this lets an application remember an icon's JUjlk 
placement. The application can thus continually update the icon (for example, to represent | 
time-of-day) or can force a repaint by using window.! n validate (to change the shape of an 
InBasket icon, for example), normal is the picture displayed when the icon is not selected. 
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highlighted is the picture displayed when the icon is selected, ghost is the picture 
displayed when the icon is currently open, reference is the picture displayed to represent a 
remote file. referenceHighlighted is the highlighted version of reference. The desktop 
implementation will never use these last two states, but a generic reference icon 
application might. 

DefaultFileConvertProc: Selection.ConvertProc; 

DefaultFileConvertProc is a Selection.ConvertProc that knows how to convert to 
Selection.Targets of file and fileType. DefaultFileConvertProc should be called from an 
application's Implementation.convertProc for these targets, or should be provided as the 
application's Implementation.convertProc if the application has no convertProc of its own. 
No file-backed application's convertProc should need to worry about these target types. 



13.2.2 Items for Application Consumers 

These items would not ordinarily be used by an application implementation (provider), 
but rather by a consumer such as the Desktop or Folder implementation. 

Getlmplementation: procedure [NSFiie.Type] returns [Implementation]; 

Getlmplementation returns the current Implementation for a particular file type. 



13.2.3 Defaultlmplementation 

Containee supports a single global default Implementation. This default Implementation is 
used when the user operates on an NSFile for which no Implementation has yet been 
registered. 

GetOefaultlmplementation: procedure returns [Implementation]; 

GetDefaultimplementation returns the current default Implementation. 

SetDefaultlmplementation: procedure [Implementation] 
returns [ Implementation]; 

The default implementation provides a dummy display and appropriate "Sorry, Desktop is 
Unable to Open That Object" complaints in the absence of a particular implementation. 
Most clients will not call SetDefaultlmplementation. 



13.2.4 Attribute Cache 

Clients often want to use several common NSFile.Attributes, but it is awkward to pass the 
attributes around in calls, because the attributes are long, of variable length, and 
frequently not needed by the called routine. Therefore, Containee provides a cache 
mechanism that can remember and supply popular attributes. Currently, the name and 
file type attributes are supported. Containee decouples the management of in-memory 
copies of a file's name from parameter-passing arrangements. 
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GetCachedName: procedure [data:DataHandle] 
RETURNS [name: xstring.ReaderBody, ticket:Ticket]; 

GetCachedName returns the name attribute of theNSFile referred to by data. If the name 
is not in the cache, it is looked up and added to the cache, ticket must be returned (by using 
ReturnTicket) when the client is through with the name. The ticket is to prevent one client 
from changing the name while another is looking at it. 

GetCachedType: procedure [data:OataHandle] 
RETURNS [type:NSFiie.Type]; 

GetCachedType returns the type attribute of the NSFile referred to by data. If the type is 
not in the cache, it is looked up and added to the cache. 

InvalidateCache: procedure [data:DataHandie] ; 

InvalidateCache clears any information about the NSFile from the cache. It is typically 
called when the attributes of an NSFile are changed by an application. 

InvalidateWholeCacher procedure ; 

InvalidateWholeCache clears the entire cache. Information about all files is cleared. 
ReturnTicket: procedure [ticket: Ticket]; 

ReturnTicket should be called after calling GetCachedName, when the client no longer 
needs the string. 

SetCachedName: procedure [data:OataHandle, newName: xstring.Readerj; 

SetCachedName allows a client to change a cached name. Care should be taken to keep 
the filed name consistent with the cached name. 

SetCachedType: procedure [data:DataHandle, newType:NSFiie.Typel; 

SetCachedType allows a client to change a cached type. Care should be taken to keep the 
filed type consistent with the cached type. 

Ticket: type[2]; 

A Ticket is returned when GetCachedName is called. When the client is done using the 
cached name, the ticket must be returned by calling ReturnTicket. This is to prevent one 
client from changing the name while another is looking at it. 
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13.3 Errors and Signals 

Errors error [msg: xstring.Reader *- nil, error: error nil, 
errorData: long pointer to unspecified <- nil]; 

Signal: signal [msg: xstring.Reader <- nil, error: error nil, 
errorData: long pointer to unspecified nil]; 



An application's GenericProc (and PictureProc and ConvertProc) should never assume that 
it has been called by a desktop, and therefore should never call such facilities as 
Attention.Post or UserTerminal.BlinkDisplay. (The application might be called by CUSP, for 
example.) Rather, the application should raise Containee.Error or Signal with an 
appropriate message. Containee will not catch these errors. The caller of the application's 
GenericProc should catch them and do the appropriate thing. In the typical case, the 
Viewpoint desktop calls the application's GenericProc; it catches the error and calls 
Attention.Post with the passed message. CUSP could catch the error and log the message in 
a log file. 

msg is the message to display to the user, error is the actual lower- level error that ocurred 
that caused Error or Signal to be raised. errorData points to any additional data that 
accompanied the lower-level error. 

13.4 Usage/Examples 

13.4.1 Sample Containee 

The folder application is used as an example of a simple application that implements a 
particular file type. 

" Constants and global data 

folderFileType: NSFiie.Type = . . 

otdlmpi, newlmpi: containee.lmplementation <- []; 

" Containee.lmplementation procedures 

FolderGenericProc: Containee.GenericProc = 
< <[atom: Atom. ATOM, 

data: Containee.DataHandle, 

changeProc: Containee.ChangeProc *-mL, 

changeProcData: long pointer *- nil] 

RETURNS [long UNSPECIFIED] > > 
BEGIN 

SELECT atom FROM 

open = > RETURN [MakeFolder[data, changeProc, changeProcData] ]; 
props a > RETURN [MakePropertySheet[data, changeProc, changeProcData]]; 
canYouTakeSelection = > return [ iFCanlTake[] then @true else ©false]; 
takeSelection = > return [iFTake(data, move, changeProc, changeProcData] then 
©true ELSE ©false ]; 
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takeSelectionCopy a > return [if Take[data, copy, changeProc, changeProcData] 
THEN @true ELSE @false ]; 

ENOCASE = > RETURN [ 

oldFolder.genericProc [atom, data, changeProc, changeProcData] ]; 

end; 

MakeFolder: procedure [ 
data: containee.OataHandle, 
changeProc: Containee.ChangeProc nil, 
changeProcData : long pointer <- nil] 
returns [shell: StarWindowShell.Handle] a {„.}; 

Take: procedure [ 

data: Containee.DataHandle, 
copyOrMove: Selection. CopyOrMove, 
changeProc: Containee.ChangeProc ♦-nil, 
changeProcData: long pointer «- nil] 
returns [ok: boolean] = {...}; 

— initialization procedures 

InitAtoms: procedure s { 

open <-Atom.MakeAtom["Open"L]; 
props <- Atom . Ma ke Atom [ " Props " L] ; 

canYouTakeSelection ♦-Atoni.MakeAtom["CanYouTakeSelection"L]; 
takeSelection <-Atom.MakeAtom["TakeSelection"L]; 
takeSelectionCopy ^Atom.MakeAtom["TakeSelectionCopy"L]; 

}; 

Setfmplementation: procedure « { 

newlmpl.genericProc <— FolderGenericProc; 
newlmpl.pictureProc <— PictureProc; 

oldlmpi «-Containee. Setfmplementation [ folderFileType, newlmpi ]; 

}; 

" Mainline code 

lnitAtoms[]; 

Setlmplementation[]; 

13.4.2 ChangeProc example 

The folder property sheet is used to demonstrate a callback to a ChangeProc. 

DataObject: type = record [ 
fh: NSFiie. Handle, 

changeProc: Containee.ChangeProc «- nil, 
changeProcData : long pointer <- nil] ; 

Data: TYPE s long pointer to DataObject; 

MakePropertySheet: procedure [ 
data: Containee.DataHandle, 
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changeProc: Contaiinee.ChangeProc «~nil, 

changeProcData : long pointer <- nil] 

RETURNS [pSheetShell: starWindowSheii. Handle] a { 

— Pass changeProc. to Makeltems through clientData. 

my data: DataObject <- [ 

fh: NSFile.OpenByReference[@data. reference], 
changeProc: changeProc, 
changeProcData: changeProcData]; 

pSheetShell «-PropertySheet.Create [ 
formWindowltems: Makeltems, 
menultemProc: MenultemProc, 
menultems: [done: true, cancel: true, defaults: true], 
title: XMessage.Get [...], 
formWindowltemsLayout: DoLayout, 
display: false, 
clientData: @mydata]; 

}; 

Makeltems: Formwindow.MakeitemsProc s{ 

-- Make property sheet items with calls to Formwindow.MakeXXXItem. 

}; 

'fc^.J MenultemProc: PropertySheet. MenultemProc = { 

< < [shell: StarWindowSheii. Handle, formWindow: window.Handle, 

menultem: PropertySheetMenultemType, clientData: long pointer] 

RETURNS [destroy: boolean *- false] > > 
mydata: Data a clientData; 
SELECT menultem from 

done = > RETURN[destroy: ApplyAnyChanges[formWindow, mydata].ok]; 

cancel =» > RETURN[destroy: true]; 

defaults = > . . . 

enocase; 
RETURN[destroy: false]; 

}; 

ApplyAnyChanges: PR0c[fw: window.Handle, mydata: Data] returns [ok: boolean] = { 
" Collect any changes in the property sheet items. 
NSFile.ChangeAttnbutes [mydata. fh, ...]; 

BEGIN — Call the changeProc. 

data: Containee.Data [ NSFiie.GetReference [mydata.fh] ]; 
IF mydata.changeProc # nil then 

mydata.changeProc[mydata. changeProcData, @data, changedAttributes]; 
end; 

RETURN [ok: true]; 

w }; 
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13.4.3 Error and Signal Usage 

This client catches an NSFile. Error and raises Containee. Error, passing along the error and 
the NSFile.ErrorRecord: 

message: xstring.ReaderBody; 
errorRecord: NSFile.ErrorRecord; 
signal: "GENERIC- signals- nil; 
file <— NSFile. OpenByReference [reference: ... ! 

NSFile.Error « > { 
errorRecord <- error; 
signal ^L00PHOLE[NSFiie.Error, signal]; 
GOTO ErrorExIt}!; 
< < Operate on the file.>> 
NSFiie.Close[file]; 

EXITS 

ErrorExit = > { 
message <-xstring.FroinSTR[NG["NSFiie.Error"L]; 

Containee. Error [msg: ©message, error: signal, errorOata: ©errorRecord]; 



Viewpoint Programmer's Manual 13 

13.5 Index of Interface Items 

Item Page 

ChangeProc: type 6 

Data: type 4 

DataHandle: type 4 

DefaultFileConvertProc: Seiection.ConvertProc 7 

Error: ERROR 9 

GenericProc: type 4 

GetCachedName: procedure 8 

GetCachedType: procedure 8 

GetOefauitlmplementation: procedure 7 

Getlmplementation: PROCEDURE 7 

ignoreType:NSFile 4 

Implementation: type 3 

invalidateCache: procedure 8 

InvalidateWholeCache: procedure 8 

nullData:Oata 4 

PictureProc: type 6 

Pi ctu restate: type 3 

Pi ctu restate: type 6 

ReturnTiclcet: procedure 8 

SetCachedName: procedure 8 

SetCachedType: procedure 8 

SetDefaultlmplementation: procedure 7 

Setlmpiementation: procedure 2 

SignahsiGNAL 9 

SmallPictureProc:TYPE 3 

Ticket: type 8 



13-13 



13 Containee 



13-14 



ContainerCache 



14.1 Overview 

The ContainerCache interface provides the writer of a ContainerSource with a cache for 
the container's items. ContainerCache supports storing strings and client data with each 
item. 

14.2 Interface Items 

14.2.1 Cache Allocation and IVIanagement 

Handle: type = long pointer to Object; 
Object: type; 

AilocateCache: procedure returns [Handle]; 

AllocateCache returns handle on a cache that can be filled with BeginFill. The client 
should call ResetCache before calling BeginFill. 

ResetCache: procedure [Handle]; 

ResetCache clears the cache so that, for example, the cache can be refilled by calling 
BeginFill. 

FreeCache: procedure [Handle]; 

Frees the resources used by a cache. 

14.2.2 Filling the Cache 

The client initially fills a cache with items by calling BeginFill with a FillProc. The FillProc 
adds items to the cache by repeatedly calling Appendltem. 

FillProc: type = procedure [cache: Handle] 
RETURNS [errored: boolean <-false1; 
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The client provides a FillProc to the BeginFill procedure. The FillProc should fill the cache 
using Appendltem. errored is an indication of whether an error occurred during the 
filling of the cache (errored = true). 

BeginFill: procedure [ 
cache: Handle, 
fillProc: FillProc. 
clients: long pointer, 

fork: BOOLEAN <- TRUE ]; 

Clients: procedure [cache: Handle] 
RETURNS [clients: long pointer]; 

BeginFill begins filling the cache. fillProc is called to actually add items to the cache. If fork 
is TRUE, then fillProc is forked as a separate process, clients is stored with the cache and 
may be retrieved by calling Clients. 

CacheFillStatus: type = {no, inProgress, inProgressPendingAbort, 
inProgressPendingJoin, yes, yesWithError, spare }; 

StatusOfFill: procedure [cache: Handle] 
RETURNS [CacheFillStatus]; 

StatusOfFill returns the current status of the cache fill, yes indicates that the fill has 
sucessfully completed; no means the cache has not been filled yet, inProgress indicates 
that the fill is running right now. inProgressPendingAbort indicates that an abort has 
been received but the fillProc has not yet returned. inProgressPendingJoin, yesWithError, 
and spare are not currently used. 

14.2.3 Item Operations 

ItemHandle: TYPE = long pointer to ItemObject; 

ItemObject: type; 

AddData: type = record[ 

clientData: long pointer. TO ARRAY [0..0) OF WORD 
clientDataCount: cardinal. 

clientStrings: long descriptor for array of xstnng.ReaderBody]; 

An AddData record is passed to the Appendltem, lnsertltem,and Replaceltem procedures. 
clientData should contain any data that the client wants to cache with the item, usually 
some type of reference to the actual item. clientDataCount is the size (in words) of the 
clientData. clientData is copied into the cache; therefore the clientData should contain no 
pointers to other data. clientStrings should contain the strings to be displayed for the item. 
clientStrings are also copied into the cache, allowing them to be freed by the client. 

The standard use of clientStrings is to implement the ContainerSource.StringOfltemProc, 
which can be accessed efficiently using ItemNthString. See the section on item content 
operations for more details on accessing the contents of items. Caution: There are 



Viewpoint Programmer's Manual 14 



restrictions on the total length of an item (strings plus client data) that may be added to a 
cache. Currently, no item should be longer than 512 bytes. 

Appenditem: PROCEDURE [ 
cache: Handle, 
addOata: AddData] 
RETURNS [handleiltemHandle]; 

Appendltem appends an item to the end of cache. It is usually called repeatedly from 
within a FillProc. handle is a pointer that can be used to access the new item. 

DeleteNltems: procedure [ 
cache: Handle, 
item: cardinal, 

nitems: CARDINAL 

DeleteNltems deletes one or more consecutive items from cache, starting at Item. Fine Point- 
Since the cache is maintained as a contiguous string of bits, this operation is likely to be slow compared to 
Appendltem and GetNthltem. 

GetNthltem: procedure [cache: Handle, n: cardinal] 
RETURNS [ItemHandle]; 

GetNthltem returns the nth item in cache. The items are numbered from zero. Returns nil 
if no such item exists. The ItemHandle returned is not guaranteed to be valid after any 
operation that modifies the cache (DeleteNltems, Insertltem, Replaceltem). If the cache 
status is inProgress (someone is in the process of filling the cache), GetNthltem will not 
return until the nth item has been appended to the cache or until the fill is complete. 

Insertltem: procedure [ 
cache: Handle, 
before: cardinal, 
addData: AddData] 
returns [handle: ItemHandle]; 

Insertltem inserts an item in cache. The new item is inserted before item before. Note that 

all the items after this item will be renumbered. Fine Point: Since the cache is maintained as a 
contiguous string of bits, this operation is likely to be slow compared to Appendltem and GetNthltem . 

Replaceltem: procedure [ 
cache: Handle, 
item: CARDINAL, 
addData: AddData] 
RETURNS [handle: ItemHandle]; 

Replaceltem replaces the contents of item in cache with the information in addData. Fine 
Point: This operation is implemented as DeleteNltems followed by Insertltem, and so is likely to be slow 
compared to Appendltem and GetNthltem. 
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14.2.4 Item Content Operations 

Itemlndex: procedure [item: ItemHandle] returns [index: cardinal]; 

Given the handle item, Itemlndex returns its index in the cache. 

ItemClients: procedure [item: ItemHandle] returns [clientData: long pointer]; 

Returns the client data associated with item. If the client data passed in was NIL, 
clientData will be NIL. 

ItemClientsLength: procedure [item: ItemHandle] returns [dataLength: cardinal]; 

Returns the length^of the client data passed in with item. 
ItemStringCount: procedure [item: ItemHandle] returns [strings: cardinal]; 

Returns the number of client strings associated with item. 

ItemNthString: procedure [item: ItemHandle, n: cardinal] returns [xstring.ReaderBody]; 

Returns the nth client string associated with item. This operation can be used to 
implement a ContainerSource.StringOfltemProc . 

14.2.5 Marking Items in the Cache 

Whenever items are deleted or inserted in a ContainerCache, all the items are 
renumbered. This allows a client to keep track of items by marking them. ContainerCache 
keeps track of the marked items across any changes to the cache. A mark is a handle on a 
cache item that tracks the item when the item number changes. This facility is handy for 
container source implementations that use ContainerCache and want to perform all the 
various combinations of moving and copying items within the source. 

Mark: type = long pointer to MarkObject; 
MarkObject: type; 

SetMark: procedure [ 

cache: ContainerCache.Handle, index: cardinal] 
returns [mark: Mark]; 

— set a mark at index 

IndexFromMark: procedure [mark: Mark] 
returns [index: cardinal]; 
" get the current value of this mark 

MoveMark: procedure [mark: Mark, newlndex: cardinal]; 

— allows the resetting of a mark without using a new one 

FreeMark: procedure [mark: Mark]; 

— mark no longer needed 
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14.3 Usage/Examples 

After the client allocates a cache, the client starts filling the cache by calling Begin Fill 
with a FillProc. BeginFill immediately calls the FillProc. Inside the FillProc, the client will 
usually do some kind of enumeration on the source backing (for example, if the source is 
backed by files, the client would do an NSFile.List). For each item enumerated by the 
FillProc, the client builds the required strings for that item and then passes the strings 
along with any item data to Appendltem. The item data is usually some information that 
is needed to uniquely identify the item (for the file example, this might be a filelD). This 
process continues until all the items in the source have been enumerated, at which time 
the FillProc returns. 

The call to BeginFill may indicate that the FillProc should be forked into a separate process. 
This allows the enumeration of the source's items to go on in the background, an 
advantage if the source has a large number of items. If the source is being displayed in a 
ContainerWindow while this background fill is taking place, the window displays each 
new item as it is appended to the cache. Fine Point: ContainerWindow can display the items as they 
are added because during the tilling of the cache, GetNthltem will wait until the requested item is in the cache 
instead of returning with an indication that the requested item isn't available. 

Once the cache has been created, operations on the container source that owns the cache 
may cause items in the cache to become invalid. One way to bring the cache back into 
synch is to invoke BeginFill and rebuild the cache. If reenumerating the items in the 
source is expensive, items in the cache can be updated with the operations DeleteNltems, 
Insertltem, and Replaceltem. The disadvantage of these operations is that they may cause 
performance degradation. Fine Point: The current implementation tries to maintain the cache as a 
contiguous series of strings of bits to minimize swapping. Using these operations may force large amounts of data 
to be moved around or fragment the cache data. If a large number of changes are to be made, it may pay to rebuild 
the cache. 

Use of ContainerCache may not always be appropriate. In some cases, the structure of 
items in a source may be simple enough that a simple data structure in the source may 
suffice to hold all the information necessary to respond to source operations. 

14.3.1 Example of ContainerCache Use 

The following example is taken from the implementation of FileContainerSource and gives 
an example FillProc that uses Appendltem to build the cache. 

ReaderSeq: type = record [sequence length: cardinal of xstring.ReaderBody]; 

ReaderSeqPtr: TYPE == long pointer to ReaderSeq; 

WriterSeq: TYPE = RECORD (SEQUENCE length: CARDINAL OF XString.WriterBodyj; 

WriterSeqPtr: TYPE = long pointer to WriterSeq; 

FillCachelnBackground: ContainerCache.FillProc = 

<< [cache: Handle] RETURNS [errored: BOOLEAN <- FALSE] > > 
begin 

fs: FS ^ContainerCache.Clients[cachel; -- get container source context 
parentHandle: NSFlle.Handle; 

writers: WriterSeqPtr All ocateWriters [fs.colunnns. length]; 
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readers: ReaderSeqPtr *- z.NEW [ReaderSeq[fs.columnsJength]]; ^gpn^ 
Enumerator: NSFile-AttributesProc = 

BEGIN 

itemData: ItemFileOata; 
addData: ContainerCache. Add Data; 

addData <- BuildRow [fs, writers, readers, @itemData, attributes]; 
[] ^ containerCache.Appendltem [cache, addData]; 

RETURN : 

end; 

BEGIN 

parentHandle ^NSFiie.OpenByReference [fs.parentReference]; 
Process.SetPriority [Process.priorityBackground]; 
NSFiie.List [ directory: parentHandle, proc: Enumerator, 

selections: fs.selections, scope: fs. scope ]; 
NSFiie.Close [parentHandle]; 
end; 

z.FREE [©readers]; 
FreeWriters [writers]; 

return; 

end; 

BuildRow: procedure [ i 
fs: FS, 

writers: long pointer to WriterSeq, 

readers: long pointer to ReaderSeq, 

itemOata: ItemFileOataHandle, 

attributes: NSFiie. Attributes] 

returns [addData: ContainerCache.AddData] = 

BEGIN 

attr: NSFiie.Attribute; 

ci: Containee.lmplementation; 

ci Containee.Getlmplementation [attributes.type]; 
FOR i : CARDINAL IN [O..fs.columns. length) oo 
xstring.ClearWriter [@writers[i]]; 

— decide the type of column we have (passed in as Column info to 

FiieContainerSource.CreateJ and call proper format proc to format attribute(s) 
into a string ~ 
WITH column: fs.columns[i] select from 
attribute = > { 

attr AttributeFromAttributeRecord [ 

attributes, column.attr]; 
coiumn.formatProc [ci, attr, @writers[i]];}; 
extendedAttribute ■ > { 

attr *- ExtendedAttributeFromAttributeRecord [ j^!^ 

attributes, column. extendedAttr]; | 
coiumn.formatProc [ci, attr, @writers[i]];}; 
multipleAttributes s > 
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coiumn.formatProc [ci, attributes, @writers[i]]; 
endcase; 

ENDLOOP; 

itemDatat <-[id: attributes.fi lei D, type: attributes.type]; 

FOR i: CARDINAL IN [0..writers.length) do 

readers[i] «-(xstring.ReaderFromWriter [@writers[i]]) f ; 

ENDLOOP; 

addData ^ [ 

clientData: item Data, 
clientDataCount: siZE[lltemFileOata], 
dientStrings: DESCRiPTOR(readers]]; 

RETURN[addData]; 
end; 
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14.4 Index of Interface Items 



Item Page 

AddData: type 2 

AllocateCache: procedure 1 

Appendltem: procedure 3 

BeginFill: PROCEDURE 2 

CacheFillStatus: type 2 

Clients: procedure 2 

DeleteNltems: procedure 3 

FillProc: type 1 

FreeCache: procedure 1 

FreeMark:pROCEDURE 4 

GetNthitem: procedure 3 

Handle: type 1 

I ndexFromMark: PROCEDURE 4 

Insertltem: procedure 3 

ItemCiients: procedure 4 

ItemClientsLength; procedure 4 

ItemHandle: type 2 

Itemindex: procedure 4 

ItemNthString: procedure 4 

ItemObject: type 2 

ItemStringCount: procedure 4 

Mark: type 4 

MarkOb]ects:TYPE 4 

MoveMark:Procedure 4 

Object: type 1 

Replaceitem: procedure 3 

ResetCache: procedure 1 

SetMark: PROCEDURE 4 

StatusOfFill: procedure 2 
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15.1 Overview 



The Container interfaces (ContainerSource, ContainerWindow, FileContainerSource, 
FileContainerShell, and ContainerCache) provide the services needed to implement an 
application that appears as an ordered list of items to be manipulated by the user. 
Viewpoint Folders are a typical example of such an application. ContainerWindow 
provides the user interface for containers. It displays each item as a list of strings and 
handles selection highlighting, scrolling, and so forth. When a ContainerWindow is 
created, a record of procedures is passed in. ContainerWindow obtains the strings of each 
item by calling one of these procedures. ContainerWindow also performs user operations 
on items, such as open, props, delete, insert, take the current selection, and selection 
conversion by calling other procedures in the record. This record of procedures and their 
implementation is called a container source. A container source can be thought of as a 
supply (source) of items for a ContainerWindow. A container source is responsible for 
implementing container source operations on its underlying representation of the items in 
the source. 

The ContainerSource interface contains the procedure types that make up the record of 
procedures that a container source must implement. These procedure definitions 
encompass all the operations that a source of items must be able to perform. 
ContainerSource also provides a place to save data specific to a particular container 
source. 

The procedure types defined by ContainerSource fall into two categories. ActOnProc, 
CanYouTakeProc, GetLengthProc, and TakeProc are operations on the source as a whole. 
ConvertltemProc, DeleteltemsProc, ItemGenericProc, and StringOfltemProc are 

operations on the individual items within the source. 

Note that the items in a container must exhibit behavior similar to the behavior defined 
by the Containee interface, such as open, props, take selection, convert. However, also 
note that the Containee interface defines the behavior of NSFlles, whereas 
ContainerSource is totally independent of NSFile. The items in a container may be backed 
by anything. The FileContainerSource interface is an example of a container source that is 
backed by NSFlles. The ViewPoint Directory application contains examples of container 
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sources that are backed by Clearinghouse entries (such as the Filing and Printing 
dividers) and by simple strings in virtual memory (such as a domain divider). 

The ContainerCache interface provides a mechanism for caching the strings and item- 
specific data for the items in a container source. The implementor of a container source 
might find ContainerCache to be handy. 

15.2 Interface Items 



15.2.1 Handle, Procedures, and ProceduresObject 
Handle: TYPE = long pointer to Procedures; 



Procedures: type = long pointer to ProceduresObject; 

ProceduresObject: type = record [ 
actOn: ActOnProc, 
canYouTake: CanYouTakeProc, 
columnCount: ColumnCountProc, 
convertltem: ConvertltemProc, 
deieteltems: DeleteitemsProc, 
getLength: GetLengthProc, 
itemGeneric: ItennGenericProc, 
strlngOf Item : StringOf ItemProc, 
take: TakeProc]; 



Handle identifies a particular container source. Handle is a pointer to a ' pointer 
(Procedures) to a record of procedures (ProceduresObject) that are implemented by the 
container source. A container source typically exports a Create procedure that return a 
Handle. This Handle is then passed to Containerwindow. Create. Whenever 
ContainerWindow needs the container source to do something, it calls the appropriate 
procedure in the ProceduresObject by using Handle f f , and passing in the Handle Note: 
Every procedure in the ProceduresObject takes a Handle as its first parameter. Fine Point: 

Actually, ContainerWindow will call the INLINE procedures described in the INLINE section, which in turn call 
the procedures in the ProceduresObject. 

Handle is a pointer to a pointer (rather than just a pointer to the ProceduresObject) to 
allow a container source to save data specific to the source. For example, a file-backed 
source would need to keep a pointer to the file. See the section on Usage/Examples for an 
explanation of how this is done. 



15.2.2 Procedures That Operate on Individual Items 



Itemlndex: type = cardinal.- 



nullltem: Itemlndex = Itemlndex. last; 



All the procedures that operate on individual items take a Handle and an Itemlndex. An 
Itemlndex is simply a cardinal that uniquely identifies an item in the source. Note: A 
container source is an ordered list of items. An Itemlndex of "n" indicates the "nth" item in 
the source. An Itemlndex of zero corresponds to the first source item. An Itemlndex should 
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be thought of as a loose binding: the index of a particular item may change as a result of 
changes to the source. For example, if an item is deleted, all the items below it will be 
renumbered, nullltem is a constant used to represent no item or unknown item. 

StringOfltemProc: type = procedure [ 
source: Handle, 
itemlndex: Itemlndex, 
stringlndex: cardinal] 
RETURNS [xstring.ReaderBody]; 

The source's StringOfltemProc should return the string stringlndex of item itemlndex in 
source. Each item's display is composed of strings, one for each column of the container 
window. For example, an open Folder shows four columns: the icon picture, the name, the 
size, and the date, stringlndex will be IN [0..source.columnCount[]) (see also 
ColumnCountProc in the next section). If there is no such item or string, StringOfltemProc 
should return xstring.nullReaderBody. StringOfltemProc is used extensively and its 
implementation should be efficient. 

ItemGenericProc: type = procedure [ 
source: Handle, 
itemlndex: Itemlndex, 
atom: Atom, ATOM, 
changeProc: ChangeProc <-nil, 
changeProcData: long pointer <- nil] 

RETURNS [long unspecified]; 

The source's ItemGenericProc is invoked to perform an operation on one of the items in the 
container, itemlndex indicates which item to operate on. The operation, specified by 
atom, may be any one of the following set: Open, Props, CanYouTakeSelection, 
TakeSelection, TakeSelectionCopy. This procedure is just like the genericProc that a 
Containee. Implementation must provide (see the Containee interface for a complete 
description of the atoms and their return values.) changeProc must be called if the 
ItemGenericProc causes the source to change. changeProc and changeProcData are 
described in more detail below in the section on changeProc types. 

ConvertltemProc: type = procedure [ 
source: Handle, 
itemlndex: itemlndex, 
n: cardinal 

target: Selection.Target, 

zone: uncounted zone, 

info: Seiection.Conversionlnfo <- [convertf]] , 

changeProc: ChangeProc*- nil, 

changeProcData: long pointer «- nil] 

RETURNS [value: Seiiection.Vaiue]; 

The source's ConvertltemProc is invoked to convert one or more of the items in source, just 
as if the item was the current selection and Selection.Convert had been called, itemlndex 
indicates the first item to convert, n indicates how many consecutive items to convert, 
target, zone, info, and value are all identical to the parameters for Selection. ConvertProc 
(see the Selection interface). If n> 1, then info is the enumeration variant; otherwise, it is 
the convert variant. changeProc must be called if the ConvertltemProc causes the source 
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to change, for example, when an item is moved out of the source. changeProc and 
changeProcData are described in more detail in the section on changeProc types. 

DeleteltemsProc: type = procedure [ 
source: Handle, 
itemlndex: Itemlndex, 

n: CARDINALS— 1, 

changeProc: ChangeProc <- nil, 
changeProcOata : long pointer <^ nil] ; 

The source's DeleteltemsProc is invoked to delete consecutive items from source, 
itemlndex is the first item to delete, n is the number of items to delete. changeProc must 
be called if the DeleteltemsProc causes the source to change, that is, if the deletion is 
successful. changeProc and changeProcData are described in more detail in the section on 
changeProc types. 

15.2.3 Procedures That Operate on the Entire Source 

ColumnCountProc: type = procedure [ source: Handle] returns [columns: cardinal]; 

The source's ColumnCountProc should return the number of columns in source, that is, 

the number of strings in each item. Fine point: typically, the number of columns is the same as COUNT 
[ContainerWindow.ColumnHeadersj. 

GetLengthProc: type = procedure [ source: Handle] 

returns [length: cardinal, totalOrPartial: TotalOrPartial _total]; 

TotalOrPartial: type = {total, partial}; 

The source's GetLengthProc should return the total number of items currently in the 
source. This operation is performed often and should be efficient. Some container sources 
have indeterminate length until after an initial enumeration has completed (for example, 
clearinghouse enumerations). These sources may return [totalOrPartial: partial] while the 
initial enumeration is in progress. This lets the ContainerWindow display mechanism 
know that there are more items coming, while giving it some information along the way. 
Once a source knows how many items are in the source, (or for those sources that know 
right from the start how many items are in the source, (such as NSFile-backed sources), the 
GetLengthProc should return [totalOrPartial: total].) 

ActOnProc: type = procedure [ source: Handle, action: Action]; 

Action: type = {destroy, reList, sleep, wakeup}; 

The source's ActOnProc is invoked to request some action of the source. Action indicates 
what the source should or can do. 

destroy The term destroy means that the source should destroy itself, freeing 

all storage and releasing all resources associated with the container 
source instance. 
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sleep The term sleep means that the source should release whatever 

resources it can without losing information; it is a hint that the 
container source will not be used for a while. 

wakeup The term wakeup means that the source is going to be used and should 

resume its normal state, undoing whatever was done for sleep. 

relist The term reList means that the source should re-enumerate itself 

because its backing store has been changed. 

CanYouTakeProc: type = procedure [ 
source: Handle, 

selection: Selection.ConvertProc i-mi] 
RETURNS [yes: boolean]; 

The source's CanYouTakeProc is invoked to determine if the container source can take the 
selection. If selection is nil, the current selection should be used ( call Selection. Convert. ) 
Otherwise the Selection.ConvertProc is used to obtain an arbitrary selection. If the 
CanYouTakeProc returns yes = true, then the source's TakeProc may be called. Fine point: 

The Selection interface does not support passing in an arbitrary ConvertProc. It is the responsibilty of clients 
who pass in arbitrary selections to make sure the source can properly handle this case. This routine is 

intended to provide an efficient check on the compatibility of the objects being copied or 
moved. The common use of this routine is to provide feedback to the user. If a 
CanYouTakeProc returns true, the client may choose to highlight the target. This is 
normally at the level of a file-type check. More elaborate checking is not necessary; for 
example, a file-backed container source would not want to check the source for protection 
or uniqueness violations. These should be handled by the TakeProc. 

TakeProc: type = procedure [ 
source: Handle, 

copyOrMove: Seiection.CopyOrMove, 
afterHint: Itemlndex <«- nullltem, 
withinSameSource: boolean <— false, 
changeProc: ChangeProc «-nil, 
changeProcOata : long pointer <- nil, 
selection: Selection.ConvertProc nil] 
returns [ok: boolean]; 

beforeltemZero: Itemlndex = Itemlndex.LAST - 1; 

The source's TakeProc is invoked to add items to the container source. copyOrMove tells 
the source whether to do a move or a copy of the selection. afterHint indicates the item the 

new item should be inserted after. Fine point: This is only a hint to the container source, since the 
ultimate position of the new item may depend on a sort order built in to the source. afterHint defaults to 

nullltem, which indicates that the caller doesn't care where the new item goes. If afterHint 
a beforeltemZero, the source should insert the new item before the first item. 
changeProc must be called if the TakeProc causes the source to change. 
withinSameSource a true indicates to the source that the item(s) being moved or copied 
into the source are also in that same source; such as when the user moves or copies 
something from one place in a container to another place in the same container. This case 
usually involves some special case processing by the source (especially for move). 
changeProc and changeProcData are described in more detail in the next section. 
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selection indicates the objects to be moved or copied. If selection is nil, the current 
selection should be used( call Selection.Convert.) Otherwise the Selection.ConvertProc is used 
to obtain an arbitrary selection. Fine Point: Refer to the CanYouTakeProc description for further 
discussion of arbitrary selections, ok indicates whether the TakeProc was successful or not. The 
use of this routine is usually be preceded by a call to the source's CanYouTakeProc. 

15.2.4 ChangeProc Types 

A source's ConvertProc, DeleteltemsProc, ItemGenericProc, and TakeProc all take a 
ChangeProc as an input parameter. This ChangeProc must be called by the source 
whenever any item or items in the source changes. This allows the ContainerWindow 
display code to keep the display up to date with the source. For example, a call to the 
source's ItemGenericProc with an atom of Props will cause a property sheet to be displayed 
for an item. If the user then edits, for example, the name of the item, and then closes the 
property sheet, the source must detect this change, update its backing, and call the 
ChangeProc that was passed into the ItemGenericProc. This ChangeProc (supplied by 
ContainerWindow) then causes the changed item(s) to be redisplayed. 

ChangeProc: type = procedure [ 
changeProcData: long pointer, 
changelnfo: Changelnfo ]; 

A ChangeProc and changeProcData are passed to a source's ConvertProc, 
DeleteltemsProc, ItemGenericProc, and TakeProc . Since the changeProcData had to be 

allocated from someplace the changeProc must always be called, even if there were no 
changes to the source. The source must call the ChangeProc with the changeProcData and 
any changelnfo. 

Changelnfo: type = record [ 

var: select changeType: ChangeType from 
replace = > [item: Itemlndex], 

insert ■ > [insertlnfo: longdescriptorfor array of Editlnfo], 
delete = > [deletelnfo: Editinfo], 
all, noChanges a > null, 
enocase]; 

ChangeType: TYPE ■ { replace, insert, delete, all, noChanges}; 

Changelnfo is passed to the ChangeProc to tell the display code exactly what changed. A 
container source can be smart and pass specific Changelnfo (for example, "3 items were 
inserted after item 4 and 2 items were inserted after item 6" may be constructed with the 
insert variant), or be dumb and simply pass the all variant, which causes a total repaint of 
the container display, replace indicates that a single item has changed, insert indicates 
that one or more items have been inserted, delete indicates that one or more items have 
been deleted, all indicates that the entire source has been changed. 
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Editlnfo: type = record [ 
afterltem: Itemlndex, 
nitems: cardinal]; 

Editlnfo is used with the insert and delete variants of Changelnfo to indicate how many 
items have been inserted or deleted, and where they were inserted at or deleted from. 



15.2.5 Errors 

A container source may raise Error or Signal as appropriate. 

Error: error [code: ErrorCode, msg: XString. Reader nil. 
error: errors nil, errorData: long pointer to unspecified nil]; 

Signal: signal [code: ErrorCode, msg: XString. Reader <- nil. 
error: error <- nil. errorData: long pointer to unspecified <- nil]; 

A source's ItemGenericProc (and ConvertltemProc and DeleteltemsProc) should never 
assume that it has been called by a ContainerWindow, and therefore should never call 
such facilities as Attention. Post or UserTerminal.BlinkDIsplay. (The application might be 
called by CUSP, for example.) Rather, the source should raise ContainerSource. Error or 
Signal with an appropriate message. The caller of the source's ItemGenericProc should 
catch these errors and do the appropriate thing. In the typical case, the ContainerWindow 
will call the source's ItemGenericProc and catch the error and call Attention. Post with the 
passed message. CUSP could catch the error and log the message in a log file, msg is the 
message to display to the user, error is the actual lower-level error that ocurred that 
caused Error or Signal to be raised. errorData points to any additional data that 
accompanied the lower level error. 

ErrorCode: type = machine dependent {invalidParameters(O), accessError, fileError, 
noSuchltem, other, last(1 5)}; 

invaiidParameters indicates that some parameters were invalid; for example, the 

source was not the correct type (the Procedures did not match). 

accessError indicates an attempt to perform an operation that violates the 

created access option (for sources that implement access 
controls). 

fileError indicates a file systeni error (for sources that are backed by 

files). 

noSuchitem A container source implementation should raise 

Error[noSuchltem] if one of the container source's procedures is 
called with an Itemlndex for an item that is not in the source. 

Other may be raised to indicate any other problem. 

Fine point: Error and Signal are EXPORTed by the FileContalnerSource implementation since ContainerSource 

has no implementation. 
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15.2.6 INLINES 



The following INLINE procedures are provided as a convenience to clients who wish to use 
object notation when calling a container source. ContainerWindow is the only typical 
client of these procedures. 

ActOn: ActOnProc = inline {...}; 
CanYouTake: CanYouTakeProc = inline {...}; 
ColumnCount: ColumnCountProc = inline {...}; 
Convertltem: ConvertltemProc = inline {...}; 
Deleteltems: DeleteitemsProc = inline {...}; 
GetLength: GetLengthProc = inline {...}; 
ItemGeneric: ItemGenericProc = inline {...}; 
StringOfltem: StringOfltemProc = inline {...}; 
Take: TakeProc = inline {...}; 

15.3 Usage/Examples 

The reason that Handle is a pointer to a pointer (rather than just a pointer to the 
ProceduresObject) is to allow a container source to save data specific to the source. For 
example, a file-backed source would need to keep a pointer to the file. This is done in the 
following example. 

15.3.1 ContainerSource Example 

1. Declare a ContainerSource. ProceduresObject in the global frame of the module and fill it 
with the appropriate procedures. 

mySourceProcs: ContainerSource. ProceduresObject <— [ 
actOn: MyActOn, 
canYouTake: CanlTake, 
columnCount: MyCoiumnCount, 
convertltem: ConvertMyltem, 
deleteltems: DeleteMyltems, 
getLength: GetMyLength, 
ItemGeneric: MyltemGeneric, 
StringOfltem: StringOfMyltem, 
take: My Take]; 

2. Declare a record that has a ContainerSource. Procedures (Procedures, not 
ProceduresObject!) as its first field and initialize this field to point to the 
ProceduresObject declared in the global frame. The rest of the record should contain 
whatever data the source needs in order to perform all the operations it will be 
requested to perform. Also declare a pointer to this record. 

MySource: type = long pointer to MySourceObject; 

MySourceObject: TYPE = record [ 

procs: ContainerSource. Procedures <— ©mySourceProcs, 
otherStuff : . . . 1; 



15-8 



Viewpoint Programmer's Manual 



15 



3. When creating the source, allocate the MySourceObject record and fill it with any 
relevant data. Return a pointer to the Procedures field of the record (@ms.procs 
below). Note: This return value is a pointer to a ContainerSource.Procedures, which is a 
ContainerSource. Handle. 

Create: public procedure [otherStuff: . . . ] returns [source: containerSource.Handle] = { 
ms: MySource «-z.NEW [MySourceObject [otherStuff: otherStuff]]; 
RETURN[@ms.procs]; 

}; 



4. The first thing that every procedure in the ProceduresObject should do is loophole the 
ContainerSource.Handle that was passed in into a pointer (MySource) to the source's data 
record (MySourceObject). After the loophole, the fields of the source's data record can 
be directly accessed, e.g., ms. OtherStuff. This all works because the first field in the 
source's data record is a Procedures. Note that the loophole is actually performed in a 
procedure that also checks to be sure that the Procedures field of the passed source 
actually points to this source's procedures (if source | # @mySourceProcs then). 

ActOn File: ContainerSource. ActOnProc = { 
ms: MySource s ValidMySourcefsource]; 

. . . ms.otherStuff . . . 

}; 

ValidMySource: procedure [source: ContainerSource.Handle] returns [ms: MySource] = { 
IF source a NIL THEN containerSource.Error[invalidParameters]; 
IF source | # @mySourceProcs then containerSource.Error[invalidParameters]; 

}; 



15.3.2 Errors and Signals 

For example, this client catches an NSFile. Error and raises Containee. Error, passing along the 
error and the NSFile.ErrorRecord: 

message: xstring.ReaderBody; 
errorRecord: NSFile.ErrorRecord; 
signal: -GENERIC- signals- nil; 
file <~NSFiie.OpenByReference [reference: ... ! 
NSFile.Error = > { 

errorRecord «- error; 

signal ^LOOPHOLE[NSFiie.Error, signal]; 

GOTOErrorExit}]; 
" Operate on the file.-- 
NSFile.Close[file]; 
exits 

ErrorExit » > { 

message <-xstring.FromSTRING["NSFiie.Error"L]; 

ContainerSource. Error [ 
code: fileError, msg: ©message, error: signal, errorOata: (©errorRecord]; 
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15.4 Index of Interface Items 



Item 


Page 


Action: type 


4 


ActOn: ActOnProc 


7 


ActOnProc: type 


4 


beforeltemZero: Itemlndex 


5 


CanYouTake: CanYouTakeProc 


7 


CanYouTakeProc: type 


5 


Changelnfo: type 


6 


ChangeProc: type 


6 


ChangeType: type 


6 


ColumnCount: ColumnCountProc 


8 


ColumnCountProc: type 


4 


Convertltem: ConvertltemProc 


8 


ConvertltemProc: type 


3 


Deleteltems: OeleteltemsProc 


8 


DeleteltemsProc: type 


4 


Editlnfo: type 


6 


Error: error 


7 


ErrorCode: type 


7 


GetLength: GetLengthProc 


8 


GetLengthProc; type 


4 


Handle: type 


2 


ItemGeneric: ItemGenericProc 


o 
o 


ItemGenericProc: type 


3 


itemlndex: type 


2 


nullltem: Itemlndex 


2 


Procedures: type 


2 


Procedures Object: type 


2 


Signal: signal 


7 


StringOfltem: StringOfltemProc 


8 


StringOfltemProc: type 


3 


Take: TakeProc 


8 


TakeProc: type 


5 


TotalOrPartiahTYPE 


4 
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16.1 Overview 

The ContainerWindow interface supports the creation of ViewPoint-like container 
windows. A container window provides a user interface that operates on a list of objects. 
The objects are displayed in rows. Each container window has one or more columns, with 
all rows displaying the same number of columns. 

The ContainerWindow implementation maintains the display and manages user-invoked 
actions such as scrolling, selection, notifications, open within, show next/previous, and so 
forth. ContainerWindow takes a body window, a ContainerSource, and a specification of 
the columns and makes the window behave like a container. Note: This interface does not 
depend on NSFile: the objects represented by rows in the container do not have to be backed 
by NSFiles. 

16.2 Interface Items 

16.2. i Create and Destroy a ContainerWindow 

Create: procedure [ 

window: window. Handle, 
source: ContainerSource. Handle, 
columnHeaders: ColumnHeaders, 
firstltem: ContainerSource.ltemlndex <-0] 

RETURNS [ regularMenultems, topPusheeMenultems: MenuOata.ArrayHandle]; 
ColumnHeaders: type = long descriptor for array of ColumnHeaderlnfo; 
ColumnHeaderlnfo: TYPE = record [ 

width: CARDINAL, 

wrap: boolean, 

heading: xstring.ReaderBody]; 
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Create turns an ordinary window into a container window, window must be a 
StarWindowShell body window, source supplies a source of items to be displayed and 
manipulated (see the ContainerSource and FileContainerSource interfaces). 

columnHeaders describes the column widths and supplies column headings. The columns 
will be displayed in the order given by this array. For each column, width is the number of 
bits the column should take, and heading is a string that will be displayed at the top of the 
column, wrap indicates what to do when a string that the container window wants to 
display is wider than width. If wrap = TRUE , the string should be wrapped around, 
otherwise, it will be truncated. Fine Point: columnHeaders is copied by Create, so this structure may be in 
the client's local frame. 

firstltem indicates the item that should be displayed first when the container window is 
initially displayed. 

regularMenultems and topPusheeMenultems are the menu items that the container 
window needs to have in the StarWindowShell. They should be added (by the client) to the 
menu that is installed in the StarWindowShell which this container window is a part of 
(these contain menu items such as Show Next and Show Previous ). 

Destroy: procedure [window: window. Handle]; 

Destroys the data associated with the container window. Does not destroy the window 
itself. May raise Error [ notAContainerWindow ]. 

16.2.2 Item operations 

The individual containees in a container window are referred to as items (from 
ContainerSource.itemlndex) They are sequentially numbered starting with zero. 

DeleteAndShowNextPrevious: procedure [ 
window: window. Handle, 
item: ContainerSource.itemlndex, 
direction: Direction <— next]; 

Direction: TYPE = {next, previous}; 

Deletes item from the container source and the display, then displays the next or previous 
item. May raise Error[notAContainerWindow] or Error[noSuchltem]. 

GetOpenltem: procedure [window: window. Handle] 

RETURNS [item: ContainerSource.itemlndex <-ContainerSource.nullltem]; 

Returns the item that is currently open within the container. If no item is open, returns 
ContainerSource.nullltem . May raise Error[notAContainerWindow]. 
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GetSeiection: procedure [window: window.Handle] 
RETURNS [first, lastPlusOne: containerSource.ltemlndex]; 

Returns the items currently selected in the ContainerWindow. first = last = 
ContainerSource.nuliltem means there is no selection. 

Seiectltem: procedure [window: window.Handle, 
item: ContainerSource.ltemlndex]; 

Selects the specified item and implicitly calls MakeltemVisible. MakeltemVisible is in a 
friends-level interface. Note: MakeltemVisible Forces item to be visible in window. If 
there is more than a screenful of items left following item, it is put at the top of the 
window. If less than a screenful remains, item is put at the bottom of the window with as 
many items as will fit before it. May raise Error[notAContainerWindow] or 
ErrorlnoSuchlteml. 



16.2.3 Operations on a ContainerWindow 

isit: procedure [window: window.Handle] returns [yes: boolean]; 

Returns true if the window passed in is a ContainerWindow. 

GetSource: procedure [window: window.Handle] 
RETURNS [source: ContainerSource. Handle]; 

Returns the ContainerSource associated with this window. May raise 
Error[notAContainerWindowl. SetSource allows the client to change the source and the 
SourceModifyProc allows the client to modify the source. 

SetSource: procedure [ 

window: window.Handle, newSource: ContainerSource. Handle] 
RETURNS [oldSource: Handle]; 

SourceModifyProc: type » procedure [ 

window: window.Handle, source: ContainerSource.Handle] 
returns [changelnfo: Changelnfo]; 

ModifySource: procedure [window: window.Handle, proc: SourceModifyProc]; 

ModifySource calls the source modification proc from within its monitor. 

Update: procedure [window: window.Handle]; 

Called when the correspondence between the source and the display is invalid. Items in 
the display will be redisplayed to reflect any changes in the source. May raise 

ErrOr[nOtAContainerWindOw]. Fine Point: Clients will not normally need to call this routine unless they 
manipulate the source directly. All user- initiated operations on a ContainerWindow cause the display to be 
updated automatically. 
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16.2.4 Errors 




Error: error [code: ErrorCode]; 

ErrorCode: type = machine dependent {notAContainerWindow(O), noSuchltem, last(7)}; 

Any operations that operate on a container window may raise this error. 
notAContainerWindow is raised if the window passed in is not a container window (i.e., 
was not passed to Create). noSuchltem may be raised if an operation specifies a non- 
existent item. 



The following example is taken from the implementation of the FileContainerSheli 
interface. It illustrates the steps involved in creating a container window: creating a 
container source, creating a StarWindowShell, creating a body window inside the shell, 
creating the container window, and finally merging the menu items returned by 
ContainerWindow.Create with its own menu commands and installing those commands in 
the shell. It also gives a sample StarWindowShell transition procedure that will destroy 
the container source and the container window. 

-- From FileContainerShelllmpl.mesa 

MenultemSeq: type = record [ 

sequence length: cardinal of MenuOata.ltemHandle]; 

Create: public procedure [ 
file: NSFiie.Reference, 

columnHeaders: ContainerWindow.ColumnHeaders, 
columnContents: FileContainerSource.ColumnContents, 
regularMenuitems, topPusheeMenultems: MenuData.ArrayHandle <r- nil, 
scope: NSFiie.Scope <- [], 

position: ContainerSource.ltemlndex 0, 
options: FileContainerSource. Options []] 
returns [shell: starwindowsheii. Handle] = 

begin 

body: window.Handle <- nil; 
source: ContainerSource.Handie <— nil; 

cwRegularMenultems, cwTopPusheeMenultems: MenuData.ArrayHandle; 

mergedMenultems: long pointer to MenultemSeq <— nil; 

menu: MenuOata.MenuHandle; 

name: xstring.ReaderBody; 

ticket: Containee. Ticket; 

data: Containee. Data ^[filej; 

type: NSFiie.Type; 

smallPicture: xstring.Character; 



16.3 Usage/Examples 



IF file = NSFiie.nullReference THEN return [ [nil] ]; 

source FileContainerSource.Create [ 
file: file. 
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columns: columnContents, 
scope: scope, 
options: options]; 



[name, ticket] «~Containee.GetCachedName [@data]; 

type <— Containee.GetCachedTy pe[@data] ; 

smallPicture <-containee.Getlmplementation(type].smallPicture; 



shell StarWindowShell.Create [ 
name: @name, 
namePicture: smallPicture, 
sleeps: false, 

transitlonProc: DestroyProc]; 



Containee.ReturnTicket [ticket]; 



body i- starWindowSheii.CreateBody [sws: shell, box: [[0,0],[700, 29999]]]; 

[cwRegularMenultems, cwTopPusheeMenultems] ContainerWindow.Create [ 
window: body, 
source: source, 

columnHeaders: columnHeaders, 
firstltem: position]; 

mergedMenultems «- MergeMenuArrays [cwRegularMenultems, regularMenultems]; 
IF mergedMenultems # NIL THEN 

BEGIN 

menu <— MenuOata.CreateMenu [ 

zone: starWindowSheii.GetZone(shell], 
title: NIL, 

array: DESCRiPTOR(mergedMenultems], 

copyltemslntoMenusZone: true ]; 
starWindowSheii.SetRegularCommands [shell, menu]; 
z.FREE[@mergedMenultems]; 
end; 



mergedMenultems «- MergeMenuArrays [cwTopPusheeMenultems, 

topPusheeMenultems]; 

menu <- MenuOata.CreateMenu [ 

zone: starWindowShell.GetZone[shell], 

title: NIL, 

array: DESCRiPTOR[mergedMenultems], 

copyltemslntoMenusZone: false ]; 
starWindowSheil.SetTopPusheeCommands [shell, menu]; 
RETURN [shell]; 
end; 

DestroyProc: StarWindowShel I. TransitlonProc = 
< <[sws: StarWindowShell. Handle, state: StarWindowShell. State] > > 
BEGIN 

IF State a dead then { 

cw: Window. Handle <— GetContainerWindow[sws]; 
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source: ContainerSource.Handte <-GetContainerSource[sws]; 

containerSource.ActOn [source, destroy]; 

ContainerWindow.DeStroy[cw]; }; 
return; 
end; 

MergeMenuArrays: proc [itemArrayl, itemArray2: MenuOata.ArrayHandle] 
RETURNS [mergedSeq: long pointer to MenultemSeq] = 

BEGIN 

i: CARDINAL <-0; 

IF itemArrayl ■ niland itemArray2 = nil then return[nil]; 

mergedSeq ^z.NEW [MenultemSeq[itemArray1. length + itemArrayZ.LENGTH]]; 
for): cardinal in [0.. itemArrayl. length) do 

mergedSeq[i] itemArrayl (]]; 

i <-i + 1; 

endloop; 

for j: cardinal IN [0..itemArray2.LENGTH) do 

mergedSeq[i] ♦-itemArray2(j]; 

i «-i + 1; 

endloop; 
RETURN[mergedSeq]; 
end; 
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16.4 Index of Interface Items 



Item Page 

ColumnHeaderlnfo: type 1 

ColumnHeaders: type 1 

Create: procedure 1 

DeleteAndShowNextPrevious: procedure 2 

Destroy: procedure 2 

Direction: TYPE 2 

Error: error 4 

ErrorCode: type 4 

GetOpenltem: procedure 2 

GetSeiection: procedure 3 

GetSource: procedure 3 

ISit: PROCEDURE 3 

MakeltemVisible: procedure; 3 

ModifySource.PROCEDURE 3 

Selectltem: procedure 3 

SetSourcetPROCEDURE 3 

SourceModifyProcrPROCEDURE 3 

Update: PROCEDURE 3 
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17.1 Overview 

In performing various functions, an application may wish to save and retrieve state from 
one notification to the next. This is an immediate consequence of the notification scheme, 
for a tool cannot keep its state in the program counter without stealing the processor after 
responding to an event. Thus, it becomes necessary for the application to explicitly store 
its state in data. Because most notification calls to the application provide a window 
handle, it is natural to associate these contexts with windows. The context mechanism is 
provided as an alternative to the application's having to build its own associative memory 
to retrieve its context, given a window handle. 

Typically, an application obtains a unique Type for its context data by calling Uniquelype 
in the start-up code for the application. Then whenever a window is created, the client 
allocates some context data and calls Create to associate that data with the window. 
Whenever the client is called to perform some operation on the window (For example, to 
display the contents of the window or to handle a notification), it calls Find to retrieve the 
data saved with the window. Finally, when the window is being destroyed, the client 
(orViewPoint) calls Destroy, which calls the client's DestroyProcType to give the client an 
opportunity to free the data. 

17.2 Interface Items 

17.2.1 Creating/Destroying a Context 

Uniquelype: procedure returns [type: Type]; 

The procedure Uniquelype is called if a client needs a unique Type not already in use by 
either Viewpoint or another client. If no more unique types are available, the error 
Error(tooManyTypes] is raised. 

Create: procedure [ 

type: Type, data: Data, proc: DestroyProcType, window: Window.Handle]; 
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The procedure Create creates a new context of type type that contains data. The context is 
associated with window; it is said to "hang" on the window. If window already possesses a j 
context of the specified type, the error Error[duplicateType] is raised. If the window is nil, 
the ERROR Error[windowlsNIL] is raised. The proc is supplied so that when the window is 
destroyed is all of the context data can be destroyed (deallocated). 

Type: type = machine dependent{ 
all(0),first(1). lastAilocated(37737B), last(37777B)}; 

Type is unique for each client of the context mechanism. An argument of this type is 
passed to most of the procedures in this interface so that the correct client data can be 
identified. 

Data: type = long pointer to unspecified; 

Data is the value that a client may associate with each window. It is typically a pointer to 
a record containing the client's state for some window. 

DestroyProcType: type = procedure [Data, Window.Handle]; 

A DestroyProcType is passed to Create so that the client can be notified when the context 
should be destroyed. This may be the result of the window being destroyed. 

Destroy: procedure [type: Type, window: Window.Handle]; jifH. 

j 

The procedure Destroy destroys a context of a specific type on window. If the context 
exists on the window, it will call the DestroyProcType for the context being destroyed. 

DestroyAII: procedure [window: Window.Handle]; 

The procedure DestroyAII destroys all the contexts on window. Fine Point: DestroyAII can be 

very dangerous because ViewPoint keeps its window-specific data in contexts on the window. DestroyAII should 
not be used except in special circumstances. It is called by the routines that destroy windows. 

NopDestroyProc: DestroyProcType; 

The procedure NopDestroyProc does nothing. It is provided as a convenience to clients 
that do not want to create their own do-nothing DestroyProcType to pass to Create. 

SimpleDestroyProc: DestroyProcType. 

The procedure SimpleDestroyProc merely calls the system heap deallocator on the data 
field. It is provided for clients whose context data is a simple heap node in the system zone. 

17.2.2 Finding a Context on a Window 

Find: procedure [type: Type, window: Window.Handle] returns [Data]; 

The procedure Find retrieves the data field from the specified context for window, nil is ! 
returned if no such context exists on the window. 
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FindOrCreate: procedure [ 

type: Type, window: Window.Handie, createProc: CreateProcType] returns [Data]; 

The procedure FindOrCreate solves the race that exists when creating new contexts in a 
multi -process environment. If a context of type type exists on window, it returns the 
context's data; otherwise, it creates a context of type by calling createProc and then 
returns data. If the window is nil, the error Error[windowlsNILl is raised. 

CreateProcType: type = procedure returns [Data, DestroyProcType]; 

CreateProcType is used by FindOrCreate. The procedure passed in as an argument to 
FindOrCreate is called to create a context only if a context of the appropriate type cannot 
be found. 

Set: PROCEDURE [type: Type, data: Data, window: Window.Handie]; 

The procedure Set changes the actual data pointer of a context. Subsequent Finds will 
return the new data. Note: The client can change the data pointed to by the data field of a 
context at any time. This could lead to race conditions if multiple processes are doing 
Find's for the same context and modifying the data. It is the client's responsibility to 
MONITOR the data in such cases. If the window is nil, the error Error[windowlsNIL] is 
raised. 



17.2.3 Acquiring/Releasing the Context 

Acquire: procedure [type: Type, window: Window.Handie] returns [Data]; 

The procedure Acquire retrieves the data field from the specified window, nil is returned if 
no such context exists on the window. It also locks the context object so that no other calls 
on Acquire or Destroy with the same type and window will complete until the context is 
freed by a call on Release. 



Release: procedure [type: Type, window: Window.Handie]; 

The procedure Release releases the lock on the specified context object for window that 
was locked by the call on Acquire. If the specified context cannot be found or it is not 
locked, Release is a no-op. 



17.2.4 Errors 



ErrorCode: type = {duplicateType, windowlsNIL, tooManyTypes, other}; 

duplicateType is raised by Create if a context of the given type already exists on the 
window passed as an argument. 

windowlsNIL is raised if the client has passed in a nil window. 

tooManyTypes is raised if UniqueType has been called too many times. 



Error: error [code: ErrorCode]; 

Error is the only error raised by any of the Context procedures. 
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17.3 Usage/Examples 

Acquire and Release can be used in much the same manner as a Mesa monitor (See Mesa 
Language Manual: 610E00150). It is important that the client call Release for every 
context that has been obtained by Acquire; this is not done automatically. The cost of 
doing an Acquire is barely more than entering a MONITOR and doing a Find. Using this 
technique allows the client to monitor his data rather than his code. 

If it is necessary for several tools to share global data, it is possible to place a context on 
Window. rootWindow that is never destroyed, even when the bitmap is turned off. To share 
a Type without having to EXPORT a variable, it is possible to use one in the range 
(tastAllocated..lastl. Contact the support organization to have one allocated to you. 

17.3.1 Example 

myContextType: Context.Type <— Context-UniqueTypeH; 

MyContext: type = long pointer to MyContextObject; 

MyContextObject: type = record [...]; 

sysZ: UNCOUNTED zone ^ Heap.systemZone; 

MakeShellAndBodyWindow: procedure s { 

myContext: MyContext <— sysZ.NEW [MyContextObject [ 

— initialize fields of MyContextObject — ] ] ; 

— Note: If some field of MyContextObject was a pointer to some more allocated 
storage, then t/ieContext-SimpleDestroyProc would not be used, but rather a client 
supplied DestroyProcType would have to be provided that freed both 
MyContextObject and the storage pointed to by MyContextObject 

shell: starwindowSheii. Create [...]; 

body: starWindowSheii.CreateBody [sws: shell, 

repaintProc: MyRepaint, 

bodyNotifyProc: MyNotify]; 
Context.Create [type: myContextType, 

data: myContext, 

proc: context.SimpleDestroyProc, 

window: body]; 
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MyRepaint: PROCEDURE [window: window.Handle] a { 
myContext: MyContext <r- FindContext [window]; 

}; 

MyNotify: TiP.IMotifyProc » { 

myContext: MyContext FindContext [window]; 

}; 

FindContext: procedure [window: window.Handle] 
RETURNS [myContext: MyContext] { 
myContext <—Context.Find [myContextType, window]; 
IF myContext = nil then error; 

}; 



Context 



17.4 Index of Interface Items 



Item Page 

Acquire: procedure 3 

Create: procedure 1 

CreateProcType: type 3 

Data: type 2 

Destroy: procedure 2 

DestroyAll: procedure 2 

Destroy ProcType: type 2 

Error: error 3 

ErrorCode: type 3 

Find: procedure 2 

FindOrCreate: procedure 3 

NopDestroyProc: procedure 2 

Release: procedure 3 

Set: procedure 3 

SimpleDestroyProc: procedure 2 

Type: type 2 

UniqueType: procedure 1 
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18.1 Overview 

The Cursor interface provides a procedural interface to the hardware mechanism that 
implements the cursor on the screen. Several cursor shapes are defined in this interface, 
as well as operations for client-defined cursors. Because there is a single global cursor, it 
should be manipulated only through this interface and only from the notifier process. 

The major data structure defined in this interface is the Object, which defines not only the 
array of bits that defines the picture of the cursor, but also its hot spot. The hot spot of a 
cursor consists of the coordinates within the 16-by-16 array that are meant to indicate the 
screen position pointed to by the mouse. The hardware position of the cursor is always in 
the upper-left corner of the bit array. For many cursor shapes, this position is not where 
the cursor points. For example, the pointRlght cursor shape is a right-pointing arrow and 
has its hot spot at the tip of the arrow. 

There can be up to 256 different cursors, limited by the size of the Type enumeration. The 
first several types are system-defined. Clients may call Uniquely pe to allocate an unused 
type for their own use. 

The typical use of this interface is to change the cursor either by calling Set to set it to one 
of the system-defined cursors or by calling Store. The cursor may be restored by saving it 
into an Object by calling Fetch before it is changed. 

18.2 Interface Items 

18.2.1 Major Data Structures 

Handle: TYPE = long pointer to Object; 

Object: TYPE = RECORD [info: Info, array: UserTerminal.CursorArray]: 
Info: TYPE = RECORD [type: Type, hotX: [0,.16), hotY: [0..16)]; 
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Type: TYPE = MACHINE DEPENDENT{ 

blank(O), bullseye(1), confirm(2),ftpBoxes(3), hourGlass(4), lib{5), menu(6), 
mouseRed(7), pointDown(8), pointLeft(9), pointRight(IO), pointUp(11), 
questionMarl<(12), scrollDown(13), scrollLeft(14), scrollLeftRight(15), scrollRight(16), 
scrollUp(17), scrollUpDown(18), textPointer(19), groundedText(20), move(21), 
copy(22), sameAs(23), adjust(24), row(25), column(26), last(377B)}; 

Object defines the type and hot spot of the cursor as well as the 16-by-16 array of bits that 
represent the cursor's picture. 

The cursors in the subrange Type[blank.. column] are system-defined. 
Info contains the type and the hot spot of a cursor. 
Defined: TYPE = Type[blank.. column]: 

Defined is the subrange of Type that contains the system-defined cursors. 

18.2.2 Setting the Cursor Picture 

Set: PROCEDURE [type: Defined]; 

Set sets the displayed cursor to be one of the system-defined cursors. 
Store: procedure [h: Handle]; 

Store sets the displayed cursor to the cursor described by h. 
StoreCharacter: procedure [c: xchar.Character]; 

StoreCharacter stores the system font picture of character c into the cursor. The info is set 
to [type: column.succ, hotX: 8, hotY: 8]. 

StoreNumber: procedure [n: cardinal]; 

StoreNumber sets the cursor picture to be the number n MOD 100. If n is less than 10, the 
single digit is centered in the cursor. The info is set to [type: column. succsucc, hotX: 8„ 
hotY: 8]. 

18.2.3 Getting Cursor Information 

Fetch: procedure [h: Handle]; 

Fetch copies the current cursor object into the object pointed to by h. 
Getlnfo: procedure returns [info: Info]; 
Getinfo returns the hot spot and type of the current cursor. 
FetchFromType: procedure [h: Handle, type: Defined]; 
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FetchFromType copies the system-defined cursor object corresponding to type into the 
object pointed to by h. 

18.2.4 Miscellaneous Operations 

MovelntoWindow: procedure [ 

window: window. Handle, place: window. Place]; 

MovelntoWindow moves the cursor to the window-relative place in window. 

Swap: PROCEDURE [old, new: Handle] ; 

Swap places the displayed cursor object in old ^ and Stores the new. It is equivalent to 
Fetch[old]; Storefnew], 

18.2.5 Client- Defined Cursors 

UniqueType: procedure returns [Type]; 

UniqueType lets clients assign a unique type to their defined cursors. It returns a Type 
that is different from all predefined types and from any that has previously been returned 
by UniqueType. The value is only valid during the current boot session. 

18.2.6 Cursor Picture Manipulation 

Invert: procedure returns [boolean]; 

Invert inverts each bit of the cursor picture and inverts the positive/negative state of the 
picture. It returns true if the new state of the cursor is positive. 

MakeNegative: procedure; 

MakeNegative is equivalent to MakePositive followed by Invert. It sets the 
positive/negative state of the cursor to negative. 

MakePositive: procedure; 

MakePositive sets the positive/negative state of the cursor to positive. The state is set to 
positive whenever Set or Store is invoked. 

18.3 Usage/Examples 

The following example shows a client setting the cursor to an hourglass while performing 
some time-consuming action. It first saves the current cursor and restores it when it is 
done, if the action did not change the cursor. If the client knew what the cursor should be, 
it would not have to be saved, but could be unconditionally set . 

savedCursor: Cursor.Object; 

Cursor.Fetch[@savedCursor]; 
Cursor.Set[hourglass] 
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— do action - 

iFCursor.Getlnfo[].type = hourglass then Cursor.Store[@savedCursor]; 

StoreCharacter is typically used to put small pictures in the cursor by using characters 
obtained from simpleTextFont.AddClientDefinedCharacter. 
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19.1 Overview 

Directory provides a mechanism for clients to add dividers to the directory icon. Directory 
maintains a directory divider containing three top-level dividers, the workstation divider, 
containing those objects that exist on a per-workstation basis; the user divider, containing 
those objects that exist on a per-user or per-desktop basis; and the network divider, 
containing those objects that exist in the internet. See the Divider and CHDivider 
interfaces for more information about dividers . 

19.1.1 Predefined Divider Structure 

Directory automatically creates a top-level divider, which backs the directory icon. To this 
divider it adds the workstation divider, the user divider, and the network divider. It adds 
three entries to the workstation divider: the prototype folder, the office aids divider, and 
the local devices divider. The user divider is emptied at each logout. Clients of the user 
divider should add their entries at each logon. Directory also automatically adds the 
organization divider to the network divider, and the domain divider to the organization 
divider. Clients can add entries to the domain divider, (see Figure 1^.1). See the Prototype 
interface for details of how to add prototype icons to the prototype folder, and the Divider 
interface for details of how to add entries to the office aids, local devices, and user dividers. 

19.2 Interface Items 

19.2.1 Adding Items to a Predefined Divider 

DividerType: type = {top, ws, user, domain, localDevices, off iceAids}; 

A parameter of type DividerType is passed to AddDividerEntryto specify one of the 
predefined dividers. A value of top specifies adding a new top-level divider. 

AddDividerEntry: procedure [ 
divider: DividerType, 
type: NSFiie.Type, 
label: xstring.Reader, 
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data : long pointer nil, 
convertProc: Divider.ConvertProc <— nil, 
genericProc: Divider.GenericProc <— nil]; 

AddDividerEntry adds an entry to the divider specified by divider. If divider is equal to 
top, a new top-level divider is added, type specifies the NSFile.Type of the entry and is used 
to obtain the Containee.lmpiementation for the entry, label is used to label the entry when 
it appears in the divider's container window. The xstring. Reader bytes will be copied, data 
is an optional data pointer to be supplied in subsequent calls to the GenericProc and the 
ConvertProc. convertProc is a Divider.ConvertProc for the entry and genericProc is a 
Divider.GenericProc for the entry. (See the Divider interface for details.) Fine Point: The 
predefined dividers are actually implemented using the Divider interface. AddDividerEntry is actually the same 
as Divider.AddEntry with the handle arguement replaced by a Directory.DividerType. 

19.2.2 GetDividerHandle 

GetDividerHandie: procedure [divider: DividerType] returns [handle: Divtder.Handle]; 

GetDividerHandle returns the Divider.handle for the predefined divider specified by 
divider. Clients can use this handle to manipulate the predefined divider with the Divider 
interface. (See the Divider chapter for more information.) 

19.3 Usage/Examples 

See the Divider and CH Divider interfaces for examples of how to add entries to the 
directory. The Divider interface also shows the implementation of AddDividerEntry. 
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Figure 19.1 Predefined Divider Structure 
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19.4 Index of Interface Items 

Item Page 

AddDividerEntry: procedure 1 

GetDividerHandle: procedure 2 

DividerType: type 1 
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20.1 Overview 

The Display interface provides elementary routines for painting into windows on the 
display screen. Procedures are provided for painting points, lines, bitmaps, repeating 
patterns, boxes filled with black, gray, white, or small patterns, circles, circular arcs, 
ellipses, conies, and for painting a brush as it moves along an arbitrary trajectory. 
Another procedure allows shifting the current content of a window. Procedures for 
painting text are available in the SimpleTextDisplay interface. 

The Window interface supplies facilities for managing windows, and the introduction 
section of the Window chapter describes the window coordinate system and the process of 
painting into a window. The reader should be familiar with that material. 

As described in the Window chapter, the display background color, which is represented 
by a pixel value of zero, is commonly called white and a value of one called black. Note 
however, that the display hardware also has the ability to render the picture using zero for 
black and one for white. Clearing or erasing an area of the screen means setting all of its 
pixels to zero, or "white." 

The Display interface currently contains procedures that apply to text, namely Block, 
MeasureBlock, ResolveBlock, Character, Text, Textlnline. They are not supported. Text 
painting operations are provided by the SimpleTextDisplay interface. 

As described in the Window chapter, the standard way for a client to paint into its window 
is to update its data structures, invalidate the portion of its window that needs to be 
painted, and then call a window. Validate routine. Window will respond by calling back 
into the client's display procedure to do the painting. Nonstandard ways of painting are 
discussed in the Usage/Examples section of this chapter. 

20.2 Interface Items 

20.2.1 Painting Filled Boxes, Horizontal Lines, and Vertical Lines 
Handle: type » window.Handle; 
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Black: procedure [window: window.Handie, box: window. Box]; 
Invert: procedure [window: window.Handie, box: window. Box]; 
White: procedure [window: window.Handie, box: window. Box]; 

Black and White paint black and wiiite boxes. Invert changes all black pixels to white and 
all white pixels to black in the box. These procedures perform their operation on the 
specified box in window. Horizontal and vertical black lines can be painted by using Black 
with a box that is one pixel wide or tall. 

Display.Handle is provided for backward compatibility. 

20.2.2 Painting Bitmaps and Gray Bricks 

The procedures in this section allow the client to paint bitmaps and gray bricks into a 
window. Bitmaps and gray bricks are described in the Mesa Processor Principles of 
Operation. 

The first items below define some convenience types and constants that are used in 
conjunction with bitmaps and painting. 

BitAddress: type a Environment.BitAddress; 

DstFunc: type = BitBlt.DstFunc; 

BitBitFlags: type s BitBlt.BitBltFlags; 

A BitBlt.BitBltFlags is an argument of the Bitmap and Trajectory operations. These flags 
control how source pixels and existing display pixels are combined to produce the final 
display pixels. The flag constants defined below cover most of the common cases. 
BitBlt.BitBltFlags are described in detail in the Mesa Processor Principles of Operation. 

replaceFlags: BitBitFlags a [ 

direction: forward, disjoint: true, disjointltems: true, gray: false, 
srcFunc: null,dstFunc: null, reserved: 0]; 

replaceFlags is used to paint opaque black and opaque white from a bitmap. Source pixels 
from the bitmap overwrite the previous display pixels. 

textFlags, paintFlags: BitBitFlags » [ 

direction: forward, disjoint: true, disjointltems: false, gray: false, 
srcFunc: null, dstFunc: or, reserved: 0]; 

textFlags and its synonym paintFlags are used to paint opaque black and transparent 
white from a bitmap source. Black source pixels cause black display pixels. White source 
pixels leave display pixels unchanged. 

xorFlags: BitBitFlags > [ 

direction: forward, disjoint: true, disjointltems: false, gray: false, 
srcFunc: null, dstFunc: xor, reserved: 0]; 
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xorFlags is used with a source bitmap to selectively video invert existing display pixels. 
^i^gf/ Video inverting is the process of changing white to black and black to white. Black source 

pixels cause the existing display pixels to be inverted. White source pixels leave display 
pixels unchanged. 

paintGrayFlags, bitFlags: BitBltFlags a [ 

direction: forward, disjoint: true, disjointltems: true, gray: true, 
srcFunc: null, dstFunc: or, reserved: 0); 

paintGrayFlags is used to paint opaque black and transparent white from a gray brick 
source. Black source pixels cause black display pixels. White source pixels leave display 
pixels unchanged. 

replaceGrayFlags, boxFlags: BitBltFlags a [ 

direction: forward, disjoint: true, disjointltems: true, gray: true, 
srcFunc: null, dstFunc: null, reserved: 01; 

replaceGrayFlags is used to paint opaque black and opaque white from a gray brick source. 
Source pixels overwrite the previous display pixels. 

xorGrayFlags, xorBoxFlags: BitBltFlags a [ 

direction: forward, disjoint: true, disjointltems: true, gray: true, 
srcFunc: null, dstFunc: xor, reserved: 0]; 

xorGrayFlags is used with a source gray brick to selectively video invert existing display 
pixels. Black source pixels cause the existing display pixels to be inverted. White source 
pixels leave display pixels unchanged. 

eraseFlags: BitBltFlags » [ 

direction: forward, disjoint: FALSE, disjointltems: FALSE, gray: FALSE, 
srcFunc: complement, dstFunc: and, reserved: 0]; 

eraseFlags is used to erase objects. Previous display pixels are overwritten. 

Bitmap: procedure [ 

window: window. Handle, box: window. Box, address: Environment. BitAddress, 
bitmapBitWidth: cardinal, flags: BitBit.BitBltFlags <- paintFlags]; 

Bitmap paints the bitmap described by address and bitmapBitWidth into box in window, 
using flags to control the interaction with pixels already being displayed. Bitmap may be 
used to display a gray pattern that is not aligned relative to the window origin, 
box.dims.w must be less than or equal to bitmapBitWidth; this is not checked, flags. gray 
is ignored. 

BitAddressFromPlace: procedure [ 

base: Environment.BitAddress, X, y: natural, raster: cardinal] 
returns [Environment.BitAddress]; 

BitAddressFromPlace returns the Environment.BitAddress of the pixel at coordinates x and y 
in the bitmap described by base, raster is the number of pixels per line in the bitmap. This 
^■"^ procedure is useful for calculating the address parameter of Bitmap. 
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Brick: type = long descriptor for array of cardinal; 

Bricks are used by Gray and Trajectory to describe a repeating pattern with which to fill an 
area. The maximum size of a Brick is 16 words; each word is one row of the pattern. 

fiftyPercent: Brick; 

f iftyPercent is a brick containing a 50% gray pattern. 
Gray: procedure [ 

window: window. Handle, box: window. Box, gray: Brick <— fiftyPercent, 
dstFunc: BitBit.DstFunc <— null]; 

Gray uses the source gray brick to completely fill box in window. If the content of the 
brick to be displayed is not aligned with the window origin, use Bitmap instead. The table 
below describes the effect of dstFunc. 

dstFunc resulting display pixels 

null Source pixels overwrite display pixels. 

or Black source pixels cause black display pixels. White source pixels leave 

display pixels unchanged. 

xor Black source pixels cause the existing display pixels to be inverted. White 

source pixels leave display pixels unchanged. 

and Black source pixels cause black display pixels wherever the display pixels are 

already black. All other display pixels will be made white. 

20.2.3 Painting points, slanted lines, and curved lines 

The procedures below paint points, oblique straight lines, and circular arcs and conies. 

Point: procedure [window: window.Handle, point: window.Ptace]; 

Point makes the single pixel at point in window black. 

LineStyle: TYPE » long pointer to Li neStyleObject; 

LineStyleObject: TYPE » record [ 

widths: array [O..DashCnt) of cardinal, 
thickness: cardinal]; 

OashCnt: cardinal = 6; 

LineStyle describes the style of lines for the Line, Circle, Ellipse, Arc and Conic operations, 
thickness defines how many pixels wide the line is. widths defines what the dash structure 
is. Each pair of elements is number of pixels of black followed by number of pixels of white. 
For example [widths: [4,2,0,0,0,0], thickness: 2] defines the style for a dashed line, two 
pixels thick where the dashes are four pixels on, and two off. 
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Line: procedure [ 

window: window.Handle, start, stop: window.Place, lineStyle: LineStyle <-nil, 
bounds: window.BoxHandle <-nil]; 

Line paints a line from start to stop in window. If bounds # nil, the line is clipped to the 
box bounds. If lineStyle is defaulted the line is solid and a single pixel wide. 

Circle: procedure [ 

window: window.Handle, place: window.Place, radius: integer, 
lineStyle: LineStyle <-nil, bounds: window.BoxHandle <-nil]; 

Circle paints a circle centered at place in window, with the given radius. If bounds # nil, 
the circle is clipped to the box bounds. If lineStyle is defaulted the circle is solid and a 
single pixel wide. 

Ellipse: procedure [ 

window: window.Handle, center: window.Place, xRadius, yRadius: integer, 
lineStyle: LineStyle <-nil, bounds: window.BoxHandle nil]; 

Ellipse paints an ellipse with axes centered at center with an x radius of xRadius and a y 
radius of yRadius in window. The axes of the ellipse are parallel to the x-y coordinate 
system. Ellipses with oblique axes may be displayed using Conic. If bounds # nil, the 
ellipse is clipped to the box bounds. If lineStyle is defaulted the ellipse is solid and a single 
pixel wide. 

Arc: procedure [ 

window: window.Handle, place: window.Place, radius: integer, 
startSector, stopSector;; cardinal, start, stop: window.Place, 
lineStyle: LineStyle <-nil, bounds: window.BoxHandle <- nil]; 

Arc paints a portion of a circular arc centered at place in window, with the given radius. 
The arc goes from the angle defined by start in the startSector to stop in the stopSector. 
Sectors are simply octants numbered from 1 to 8, with northeast being one and increasing 
clockwise. If bounds # nil, the arc is clipped to the box bounds. If lineStyle is defaulted the 
arc is solid and a single pixel wide. 

Conic: procedure [ 

window: window.Handle, a, b, c, d, e, errorTerm: long integer, 
start, stop, errorRef : window.Place, 

sharpCornered, unboundedStart, unboundedStop: boolean, 
lineStyle: LineStyle <-nil, bounds: window.BoxHandle <-nil]; 

Conic paints the portion of the curve of the equation ax2 + bj2 + cx^^ +dx + ey + f = 0 in 
window from start to stop. Instead of passing in the last coefficient f, this procedure takes 
the errorTerm resulting from substituting start into the equation. If the conic contains 
points whose radius of curvature is less than or equal to two pixels, it must be displayed 
using multiple calls with sharpCornered set to true; otherwise sharpCornered should be 
FALSE. These "sharp-cornered" conies must be broken up into segments where the corners 
become a new segment's start and stop points. For example, a very long skinny ellipse 
must be displayed in two pieces. errorRef, unboundedStart and unboundedStop are 
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ignored. If bounds # nil, the conic is clipped to the box bounds. If lineStyle is defaulted the 
conic is solid and a single pixel wide. 



20.2c3 Painting parallelograms and trapezoids 

These types and procedures are used to paint parallelograms and trapezoids: 
FixdPtNunn: TYPE = machine dependent record [ 

SELECT OVERLAID * FROM 

wholeThing s > [li: long integer], 
parts = > [frac: cardinal, int: integer], 
enocase]; 



A FixdPtNum is a fixed-point integer with 16 bits of fraction and 16 bits of integer part. 
These numbers can be added and subtracted in a straightforward manner; while division 
and multiplication are more difficult. By using the overlaid record, the fraction and 
integer part may be obtained without shifting or dividing. FixdPtNum can express all 
practical slopes with only small errors. 



Interpolator: TYPE = record [ 
val,dVai: FixdPtNum]; 



Interpolator is used to define parallelograms and trapezoids. The dVal term is the 
derivative with respect to y; for example, x.dVal is dx/dy. 

BlackParallelogram: proc[ 

window: Handle, p: Parallelogram, dstFunc: OstFunc null]; 



Parallelogram: TYPE = record [ 

x: Interpolator, y: integer, -- upper left 
w: NATURAL, -- across top, must be positive 
h: natural]; 

BlackParallelogram paints the parallelogram defined by p in window. dstFunc acts as in 
the procedure Gray. The parallelogram is defined as below with the slope of the 
parallelogram being p.x.dVal. In Figure 20.1 the slope is two fifths. BlackParallelogrami 




Figure 20.lParallelogram definition 



optimizes a common case (e.g., diagonal lines) and runs about twice as fast as 
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GrayTrapezoid by avoiding the second interpolation, the non-integer width, and the gray 
alignment calulations 

GrayTrapezoid: proc [ 

window': Handle, t: Trapezoid, gray: Brick fiftyPercent, dstFunc: DstFunc null]; 

Trapezoid: TYPE = record [ 

x: Interpolator, y: integer, -- upper left 

w: Interpolator, - across top; must be positive 

h: natural]; 

GrayTrapezoid paints the trapezoid defined by t in window, gray and dstFunc act as in the 
procedure Gray. The trapezoid is defined in Figure 20.2 with the slope of the left side of the 
trapezoid being t.x.dVal and the slope of the right side of the trapezoid being t.x.dVal 
minus t.w.dVal. In Figure 20.2, t.x.dVal is minus one half and t.w.dVal is nine tenths. 




Figure 20.2 Trapezoid definition 



20.2.5 Painting along trajectories, shifting window contents 

Shift: PROCEDURE [window: window. Handle, box: window. Box, newPlace: window. Place]; 

Shift does a block move of a rectangular portion of window's current content. No client 
display procedures are invoked by this operation, box describes the region of window to 
be moved to newPlace. If Display does not have the pixels for a visible area of the 
destination box, that area is filled with trash and marked invalid. The client should 
validate the window when it has finished altering the window content. Shift does not 
invalidate the areas vacated by the move; if they should be repainted, the client should 
invalidate them. If Shift is executed from within a display procedure, it nevertheless does 
not clip the region painted to window's invalid area list. Invalid area lists are explained in 
the Window chapter. 
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Trajectory: public procedure [ 

window: window.Handle, box: window.Box ^window, null Box, proc: TrajectoryProc, 
source: long pointers- nil, bpl: cardinals- 16, height: cardinal <- 16, 
flags: BitBit.BitBltFlags <- bitFlags, missesChildren: boolean ^ false, 
brick: Brick «-nil]; 

TrajectoryProc: type = procedure [Handle] returns [window.Box, integer]; 

Trajectory repeatedly calls proc and paints a brush where proc specifies. The brush may 
be either a gray brick or a portion of the bitmap source. Trajectory is designed to avoid 
much of the overhead of successive calls to the normal Display routines, box is the window 
region in which painting may occur. The client must not try to paint outside box; this is 
not checked, flags controls the type of painting performed. If flags. gray sTRUE, the gray 
brick is painted; otherwise a bitmap is painted. Trajectory repeatedly calls proc for 
instructions. If proc returns a box having dims.w » 0 (e.g. window. nullBox), iteration 
ceases and Trajectory returns. Otherwise dims.w # 0; Trajectory will paint the brush and 
then loop to call proc again. The returned Box in the window is painted with the brush as 
follows. If a gray brick is being painted, the brick is used to fill completely the returned 
Box. If a bitmap is being painted, the bitmap starts at a bit offset of < integer > from 
source, is Box.dims.h high, and has bpl pixels per line. The client may wish to alter the 
brush content along the trajectory. It can do this by having source be a large bitmap 
containing several different brush patterns, and having proc return the bit offset and 
Box.dims of the desired portion. BitBit.BitBltFlags are described in §21.2.2. height and 
missesChildren are unused, proc must not call any procedures in Display or Window; 
doing so will result in a deadlock. 

20.3 Usage/Examples 

20.3.1 Special topic: Direct painting 

As described in the Window chapter, the standard way for a client to paint into its window 
is to update its data structures, invalidate the portion of its window that needs to be 
painted, and then call a window.Validate routine. Window will respond by calling back 
into the client's display procedure to do the painting. 

The client may also paint directly into a window without going through window.Validate, 
However, this direct painting approach is subject to several pitfalls and system bugs. 
Clients commonly choose direct painting only when high painting performance is 
required, such as dynamically extending an inverted selection while tracking the mouse 
or in implementing a blinking caret. 

Pitfall 1: One consequence of doing direct painting is that the window's display procedure 
must not depend on Window clearing invalid areas for it. As described in the Window 
chapter, if clearingRequired « true, Window guarantees that when the display procedure 
is called to paint the window, all of the window's pixels that should be white indeed are 
white. In that situation, the window might contain any combination of its previous 
contents and erased areas. Notice that the following sequence of events might occur: 
Window clears invalid area; then client direct paints into some part of the invalid area; 
then Window calls the window's display procedure. In this situation. Window's guarantee 
of the content of the invalid area has been voided by the parallel direct-paint activity. To 
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handle this case, the display routine must erase or otherwise completely overpaint the 
invalid areas itself. 

Pitfall 2: A client can get into trouble when it wishes to change the state of the backing 
data being displayed within a display procedure— and attempts to render the change by 
painting from the display procedure rather than invalidating the affected area and 
painting later. The display procedure's paint will be clipped to its invalid area list and 
thus will fail to achieve the desired effect. There are several ways to solve this problem: 

• Do not change backing data inside a display procedure. This approach matches nicely 
with the intended function of a display procedure. One does not expect a display 
procedure to change data— its job is to repaint. 

• Have the display procedure just invalidate the areas affected by the data being 
changed. Since a validate is already in progress, it is not necessary to call 
Window. Validate; when the display procedure returns, it will be called back with any 
new invalid areas that are waiting for it. 

• Have the display procedure call window. FreeBadPhosphorList before changing the 
data. This will allow paint from the display procedure to affect the entire window, not 
just the invalid areas. 



20.3.2 Example 1 

^^p/ The program fragments below demonstrate the use of Display in a window's display 

procedure. 

-- Enumerated TYPEs for displaying the games background. 
Background: TYPE = {gray, white}; 
background: Background ^-gray; 

DisplayBoardSW: PROC [window: window.Handle] ■ { 

- ■ This is the body window's display procedure. 
vLine, h Li ne: window. Box ; 

left, right, top, bottom: integer; 

FindBounds: PROC [window: Window.Handle, box: window.Box] a { 
left <-MiN[left, box.place.xl; 
top MiN[top, box.place.y]; 
right «-MAx[rlght, box. place.x + box.dims.w]; 
bottom <-MAx[bottom, box.place.y + box.dims.h]}; 

— paint borders and bacl<ground. 

Display. Black[window: window, box: boardAndBorderBox]; 
PaintBackground[window: window, box: boardBox]; 
vLine«-[upperLeft, [lineWidth, (boardSize-1)*unitH + 111; 
hLine<- [upperLeft, [(boardSize- 1)*unitW + 1, lineWidthjl; 
THROUGH [f irstDlmboardSizel do 

DisplayoBlack[window, vLinel; 
^pj^ DisplayoBlack[window, hLinel; 

vLine.place.x ^vLine. place. x + unitW; 
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hLine.place.y hLine.place.y + unitH; jlH^ 

ENDLOOP; 



left <- top <-integer.last; 

right <- bottom <-integer.first; 

window. EnumeratelnvalidBoxes[FindBounds] 



}; 

PalntBackground: PROC [window: window. Handle, box: window. Box] =■ { 
SELECT background FROM 

gray » > Display. Gray[window, box]; 
white = > Dispiay.White[window, box]; 

ENDCASE 

}; 

PaintStone: public proc [who: BlackWhite, u, v: Dim, play: CARDINAL] = { 
center: window. Place; 
stoneBox: window. Box; 
numStr: string [3]; 

IF -ValidCoords[u, v] then return; 
center *- BoardToPlace[u, v]; 
StoneBox <- [ 

place: [center.x - stoneRadius, center.y - stoneRadius], 
dims: [stoneSize, stoneSize]]; 

" paint a bitmap that represents game pieces. 

Display. 3itmap[ 

window: boardSW, box: stoneBox, address: outerStone, 
bitmapBitWidth: stoneBpl, flags: oispiay.paintFlags]; 

IF who = white THEN 
Display. Bitmap[ 

window: boardSW, box: stoneBox, address: innerStone, 

bitmapBitWidth: stoneBpi, flags: eraseFlags]; 



}; 

CreateGoSWS: public procedure [ 

reference: NSFiie.ReferenceRecord, name: Environment.Block ] 

RETURNS [StarWindowShell. Handle] = { 

— This procedure is invoked via a system menu. 
sz: StarWindowShell. Handle; 



starWindowSheii.SetPreferredDims [ sz, [592, 661] ]; 
— The display procedure is set here. 
boardSW <-starWindowSheii.CreateBody [ 
sws: sz. 
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repaintProc: DisplayBoardSW, 
bodyNotifyProc: TIPMe ]; 
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20.4 Index of Interface Items 



Item Page 

Arc: PROCEDURE 5 

BitAddress: type 2 

BitAddressFromPtace: procedure 3 

BitBltFiags: TYPE 2 

bitFiags: BitBit.BitBltFlags 3 

Bitmap: procedure 3 

Black: procedure 2 

BlackParallelogram: procedure 6 

boxFlags: BitBit.BitBitFiags 3 

Brick: TYPE 4 

Circle: procedure 5 

Conic: procedure 5 

DashCnt: procedure 4 

DstFunc: type 2 

Ellipse: procedure 5 

eraseFlags: BitBit.BitBltFlags 3 

fiftyPercent: Brick 3 

FixdPtNum:TYPE 6 

Gray: procedure 4 

GrayTrapezoid: PROCEDURE 7 

Handle: type 1 

Interpolater: type 6 

Invert: procedure 2 

Line: procedure 5 

LineStyle: type 4 

LineStyleObject: type 4 

paintBitFlags:BitBit.BitBltFiags 3 

paintFlags: BitBit.BitBltFlags 2 

paintGrayFlags: BitBit.BitBltFlags 3 

Parallelogram: TYPE 6 

Point: PROCEDURE 4 

replaceboxFlags: BitBit.BitBltFlags 3 

replaceFlags: BitBit.BitBltFlags 2 

replaceGrayFiags: BitBit.BitBltFlags 3 

Shift: PROCEDURE 7 

textFlags: BitBit.BitBltFlags 2 

Trajectory: procedure 8 

TrajectoryProc: type 8 

Trapezoid: type 7 

White: procedure 2 

xorBoxFlags: BitBit.BitBltFlags 3 

xorFlags: BitBit.BitBltFlags 2 

xorGrayFlags: BitBit.BitBltFlags 3 
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21.1 Overview 

Divider maintains a table of entries in memory, each representing an icon. The entries 
may or may not be backed by files. Divider does not operate on these entries directly; it 
uses a Dlvider.ConvertProc and a Divlder.GenericProc associated with each entry to operate 
on the entry. 

Also associated with each entry is an NSFile.Type used to identify the entry's 
Containee.lmplementation, a label, and a pointer to instance-specific data for the entry. 

Associated with each divider when it is created is an NSFile.Type. Divider automatically 
sets a Containee.lmplementation for this file type that supports converting the divider to a 
file and opening the divider as a container window displaying the entries. 

Also associated with each divider is a CH. Pattern specifing a clearinghouse domain and 
organization. This is inherited from a parent divider and is passed to all entries through 
the Dlvider.ConvertProc and the Divider. GenericProc associated with each entry. When the 
divider is converted to a file, the pattern is automatically encoded in an attribute of the 
file. 



21.2 Int€)rfaee Items 



21.2.1 Creating and Destroying 

Handle: type = long pointer to Object; 



Object: type; 

Create: procedure [ 
type: NSFile.Type, 
name: xstrlng.Reader, 

initialSize: cardinal <—oivider.defaultlnitialSize, 
increment: cardinal Divider. defaultlncrement. 
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zone: uncounted zone <- nil] 
RETURNS [handle: Handle]; 

Create creates a divider, type specifies the NSFile.Type the divider will have if it is 
converted to a file. A Containee. Implementation is automatically set for this type, name 
specifies the name of the divider. It will appear in the window header when the divider is 
opened, and it is the name of the file if the divider is converted to a file. The xstring. Reader 
bytes will be copied. The divider is created with a table large enough to hold initialSize 
entries. When the table becomes full, it grows by increment entries. Storage for the 
divider is allocated from zone. If zone is defaulted, the storage is allocated from a heap 
maintained by Divider. 

Destroy: procedure [handle: Handle]; 

This releases all storage associated with the given divider, handle is no longer valid when 
this procedure returns. 



21.2.2 ConvertProc and GenericProc 



Divider.ConvertProc: type = procedure [ 
data: long pointer, 
pattern: CH.Pattern, 
target: Seiection.Target, 
zone: uncounted zone. 
info: Seiection.Conversionlnfo <<- [convert[]]] 
returns [value: Seiection.Vaiue]; 



A ConvertProc is the same as a Selection. ConvertProc except that it has the extra argument, 
pattern, that specifies a clearinghouse domain and organization. See the Selection 
interface for the definition of the other arguments. The divider calls the ConvertProc 
associated with an entry, with pattern set to the domain and organization associated with 
the divider, whenever the divider is requested to convert one of its entries. 

GenericProc: type = procedure ( 
atom: Atom. ATOM, 
data: long pointer, 
pattern: CH.Pattern, 

changeProc: containee.ChangeProc nil, 
changeProcData: long pointers- nil] 
returns [long unspecified]; 

A GenericProc is the same as a Containee. GenericProc except that it has the extra argument, 
pattern, that specifies a clearinghouse domain and organization. See the Containee 
interface for the definition of the other arguments. The divider calls the GenericProc 
associated with an entry, with pattern set to the domain and organization associated with 
the divider, whenever the divider is requested to operate on one of its entries. 



DividerConvertProc: ConvertProc; 



DividerGenericProc: GenericProc; 
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These procedures may be associated with entries that themselves are dividers. In this case 
the Handle associated with the divider should be provided as the instance-specific data 
handle. See below for an example of a divider contained in another divider. 

21.2.3 Adding Entries 

AddEntry: procedure [ 
handle: Handle, 
type: NSFile.Type, 
label: xstring.Reader, 
data : long pointer nil, 
convertProc: ConvertProc <- nil, 
genericProc: GenericProc <-nil]; 

AddEntry adds an entry to the divider specified by handle, type is used to obtain the 
Containee. implementation for the entry, label is used to label the entry in the divider's 
container window. The xstring. Reader bytes will be copied, data is item-specific data for the 
entry that will be passed to the ConvertProc and GenericProc associated with the entry. If 
convertProc or genericProc is defaulted, the divider uses the corresponding procedure in 
the entry's Containee.implementation. 

21.3 Usage/Examples 

21.3.1 Fragment from Directory Impl.mesa 

This fragment is from Directorylmpl.mesa, which implements the Directory interface. It 
shows the implementation of Directory.AddDividerEntry and the mainline code to create the 
top-level directory dividers. See the CHDivider interface for more examples. 

-- File types for the directory implementation — 

directory: starFileTypes.FileType = 

folder: StarFileTypes.FileType = 

workstation: StarFileTypes.FileType = 

user: StarFileTypes.FileType = 

domain: StarFileTypes.FileType a 

- The reference for the prototype folder — 
prototypeReference: NSFiie. Reference <— 

~ Handles for the top-level dividers — 

dividers: array Directory.DividerType of Divider. Handle all [nil]; 

AddDividerEntry: public procedure [ 

divider: Directory.DividerType, 

type: NSFile.Type, 

label: xstring. Reader, 

data: long pointer <- nil, 

convertProc: Divider.ConvertProc ^ nil, 

genericProc: Divider.GenericProc «~nil] = 
begin 

Divider. Add Entry [ 
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handle: dividers[divider], 
type: type, 
label: label, 
data: data, 

convertProc: convertProc, 
genericProc: genericProc]; 

end; 

Create the top-level dividers (top will back the directory icon) - 
dividers[top] oivider.Create [directory, strlngDirectory]; 
dividers[ws] oivider.Create [workstation, string Workstation]; 
dividers[user] <— oivider.Create [user, stringUser]; 

~ Insert the workstation divider into the directory — 
Directory. AddDividerEntry [ 

divider: top, 

type: workstation, 

label: stringWorkstation, 

data: dividers[ws], 

convertProc: Divider.DividerConvertProc, 
GenericProc: Divider.DividerGenericProcl; 



- Insert the user divider into the directory -- 
Directory.AddDividerEntry [ 

divider: top, 

type: user, 

label: stringUser, 

data: dividers[user], 

convertProc: Divider.DividerConvertProc, 

genericProc: Divider.Oi viderGenericProc] ; 

- (nseff the prototype folder into the workstation divider — 

- fNote; this is an actual file that will use the folder implementation) -- 
Directory.AddDividerEntry [ 

divider: ws, 

type: folder, 

label: stringPrototypes, 

data: @prototypeReference]; 
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22.1 Overview 



ViewPoint provides a facility that permits clients to register procedures that are to be 
called when specified events occur. For example, a client may wish to be notified whenever 
a document is closed, or perhaps just the next time a document is closed. Clients need not 
know which module can cause the event. 



22.2 Interface Items 

22.2.1 Registering Dependencies 

A client wishing to be notified of some future event calls either AddDependency or 
AddDependencies, specifying the EventType and a procedure to be called when the event 
occurs, an AgentProcedure. Note: ViewPoint need not know in advance what EventType 
is implemented, nor which modules implement them. 



AddDependency: procedure [ 
agent: AgentProcedure, 
myData: long pointer to unspecified, 
event: EventType, 
remove: FreeDataProcedure «- nilI 
RETURNS [dependency: Dependency]; 

AddDependencies: procedure [ 
agent: AgentProcedure, 
myData: long pointer to unspecified, 
events: long descriptor for array of EventType, 
remove: FreeDataProcedure «-nil] 
returns [dependency: Dependency]; 



AgentProcedure: TYPE = procedure [ 
event: EventType, 

eventData, myData: long pointer to unspecified] 
RETURNS [remove, veto: boolean <- false]; 
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FreeDataProcedure: type = procedure [mydata: long pointer to unspecified]; 
Dependency: type [2]; -- Opaque - 

A dependency may be added to an event or an entire set of events by calling 
AddDependency or AddDependencies Both of these procedures return a private type, 
Dependency, that uniquely identifies that set of dependencies. The value returned may be 
saved and subsequently used in a call to RemoveDependency, which will remove the 
dependency(ies) associated with the earlier AddXXX call. The AgentProcedure may also 
remove the dependency as discussed below. 

When the specified event occurs, agent is called with the EventType, the eventData for 
the event, and the client data passed as myData. If a client wishes to "veto" the event (for 
instance, to disallow a world-swap), its AgentProcedure should return veto: true. This 
aborts the notification; that is, no other clients dependent on the event will be notified. 
However, there is no guarantee as to the order in which multiple clients are notified. If 
any client vetoes the event, the call to Notify returns true. There is no way to prevent a 
client from vetoing; instead, implemeritors of events that should not be vetoed should raise 
an ERROR if Notify returns true. To remove its dependency on an event a client's 
AgentProcedure should return remove: true. If the dependency is removed and a 
FreeDataProcedure was provided, it is called at this time to allow the client to free any 
private data. 

EventType: type = Atom.ATOM; 

The ATOM (strings) used to identify different events must of course be distinct. The 
following examples are possibilities of how this could be managed. (1) There is a central 
authority whose job it is to guarantee uniqueness of EventTypes. This could be the same 
person in charge of other such allocations, such as NSFile types. (2) There is a hierarchical 
naming structure, managed by a distributed authority. (3) There could be a file that lists 
all known EventTypes within a given system; this file would be managed by the Librarian 
to ensure against parallel allocation of new EventTypes. (In effect, this is the same as case 
1, but the Librarian takes the place of the central authority.) 

RemoveDependency: proc [dependency: Dependency]; 

NoSuchDependency: error; 

If RemoveDependency is called with a Dependency that is invalid (possibly because the 
dependency has already been removed), it raises the error NoSuchDependency. 

22.2.2 Notification 

Notify: procedure [event: EventType, eventData: long pointer to unspecified «- nil] 
returns [veto: boolean]; 

When the event occurs, the implementor calls Notify, giving it the EventType for the 
event and any implementation-specific data (eventData) required by the client 
(Presumably it is uncommon for a single operation to wish to Notify more than one event; 
this is why Notify does not take an array argument.) The Event interface then invokes 
each AgentProcedure that is dependent on the EventType. Each AgentProcedure is given 
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the EventType causing the notification, the client data provided when the dependency was 
created, and the eventData given by the implementor in the call to Notify. 

22.3 Usage/Examples 

The Event database is monitored to disallow changes while a Notify is in progress. An 
AgentProcedure is allowed to call Notify; that is, one event may trigger another. 
However, an AgentProcedure must not call AddDependency or RemoveDependency, or 
deadlock will result. Since it is relatively common for an AgentProcedure to wish to 
remove its own dependency, this facility is provided by allowing the AgentProcedure to 
return remove: true to cause the dependency to be removed. If the dependency was added 
via AddDependencies, then all of the dependencies created by that call are removed. The 
dependency is removed even though some later client of the same event might choose to 
veto the event. (If an earlier client has already vetoed, of course, then this AgentProcedure 
never gets called.) If an application requires that a dependency be removed only if the 
event is not vetoed, this can be handled by having the implementor notify a second event 
that informs clients whenever the first event is vetoed. 

Three notes regarding the preceding paragraph: First, it is possible for an 
AgentProcedure to get called twice even if it always returns remove: true. This is because 
two separate processes may be doing parallel calls to Notify Once an AgentProcedure 
returns remove: true, no subsequent calls to Notify will invoke that dependency, but any 
parallel calls in progress will complete normally. Second, since an AgentProcedure might 
be invoked at any time, it is a bad idea to call Add/RemoveDependency from within a 
private monitor, lest it lock trying to modify the Event database while a Notify is inside 
your AgentProcedure trying to grab your lock. On the other hand, the Notify call may 
very well be within the implementor's monitor, which means the AgentProcedure will 
typically be limited as to what use it can make of the eventData. Finally, if an 
AgentProcedure really needs to call Add/RemoveDependency, it may be possible to get 
the desired effect by FORKing the call, such that it will take place shortly after the 
completion of the Notify already in progress. 



22.3.1 Example 1 

-- Module interestedin an event 

eventType: Event.EventType <— Atom.MakeAtom ["SampleEvent"L]; 

EventActlon: Event.AgentProcedure = { 
- Do appropriate thing for eventType }; 

Event.AddDependency [ 
agent: EventAction, 
myData: nil, 
event: eventType]; 



- Module that signals the event 

eventType: Event.EventType Atom.MakeAtom ["SampleEvent"L]; 
eventData: — relevant info, a record, a window handle, etc. — ; 
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[] Event.Notify [event: eventType, eventData: eventData]; 

22.3.2 Example 2 

— Declare event and eventData - 
desktopWindowAvailable: Event.EventType; 
desktopWindowHandle: window.Handle ^nil; 

— Declare AqentProcedure — 
StarUp: Event.AgentProcedure = { 

If eventData = nil then return [veto: true]; 
desktopWindowHandle ^eventData }; 

— Register event this is mainline code -- 

[] <-Event.AddDependency [StarUp, nil, desktopWindowAvailable]; 

-- In Desktop code, another module, notify occurrence of the event — 
[] Event.Notify [desktopWindowAvailable, window]; 
— window/ is desktop window — 
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22.4 Index of Interface Items 



Item Page 

AddDependencies: procedure 1 

AddDependency: procedure 1 

AgentProcedure: type 1 

Dependency: type 2 

EventType: type 2 

FreeDataProcedure: type 2 

NoSuchDependency: error 2 

Notify: procedure 2 

RemoveDependency: procedure 2 
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23.1 Overview 



FileContainerShell provides a simple way to implement a container application thatis 
backed by an NSFiie. FileContainerShell takes an NSFile and column information (such as 
headings, widths, formatting), and creates a FileContainerSource, a StarWindowShell, 
and a ContainerWindow body. (See also the FileContainerSource, ContainerSource, 
StarWindowShell, and ContainerWindow interfaces). Most NSFile-backed container 
applications can use this interface, thereby greatly simplifying the writing of applications 
such as Folders and FileDrawers. 



23.2 Interface Items 



23.2.1 Create a FileContainerShell 



Create: procedure [ 
file: NSFile. Reference, 

columnHeaders: ContainerWindow.ColumnHeaders, 
coiumnContents: FileContainerSource.ColumnContents, 
regularMenultems, topPusheeMenultems: MenuOata.ArrayHandle <— nil, 
scope: NSFiie.Scope <- [], 

position: ContainerSource. item! ndex <— 0, 
options: FileContainerSource. Options []] 
RETURNS [shell: StarWindowShell.Handle]; 

Create creates a StarWindowShell with a container window as the body window, file is the 
backing for the container; it must be an NSFile with children. columnHeaders and 
coiumnContents specify all the necessary information about the columns to be displayed 
for the open container. (See the ContainerWindow and FileContainerSource interfaces for 
the specifics of the headers and contents.) scope specifies ordering, filtering, and 
direction, if any. position indicates the item that should be displayed first. 
regularMenultems and topPusheeMenultems are the menu items that the client would 
like to be put in the header of the StarWindowShell. Create puts these items in the header 
along with its own menu items, such as Show Next and Show Previous. Fine point: The client is 
responsible for putting any bottomPusheeCommands in the window header. 
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23.2.2 Operations on the Shell 

GetContainerWindow: procedure [shell: starwindowSheli. Handle] 
RETURNS [window: window. Handle]; 

Returns the container window that was created by the Create procedure. May raise 
ContainerWindow.Error[notAContainerWindow] if the shell does not have a container 
window in it. 

GetContainerSource: procedure [shell: starwindowSheii.Handle] 
RETURNS [source:containerSource.Handle]; 

Returns the container source that was created by the Create procedure. May raise 
ContainerWindow.Error[notAContainerWindow] if the shell does not have a container 
window in it. 



23.3 Usage/Examples 

23.3.1 Example: Creating a FileContainerShell and Specifying Columns 

The following example presents the procedure CreateFileSWS, which takes an 
NSFile. Reference and creates a file container shell with two columns: the name of the file 
and a version date. See the ContainerSource interface for details on columns. The name 
column uses the predefined ContainerSource.NameColumn; the version column is given in 
the example. The version column differs from the standard ContainerSource.DateColumn in 
that it displays the lastModifiedDate for directories instead of ---. 

ContentSeq: TYPE = record [ 

sequence cols: cardinal of FiieContainerSource.ColumnContentslnfo]; 
HeaderSeq: type = record [ 

SEQUENCE cols: CARDINAL OF containerwindow.ColumnHeaderlnfo]; 
NumberOfColumns: CARDINAL a 2; 

Z: UNCOUNTED ZONE 3 

CreateFileSWS: procedure [reference: NSFiie. Reference] 
RETURNS [StarwindowSheii.Handle] « 
BEGIN 

shell: StarwindowSheii.Handle; 

headers: long pointer to HeaderSeq MalceColumnHeaders[]; 
contents: long pointer to ContentSeq <- Mal<eColumnContents[]; 
shell ^ FileContainerShell,Create[ 
file: reference, 

coiumnHeaders: DESCRiPTOR[headers], 

columnContents: DESCRiPTOR[contents]]; 
z.FREE[@headers]; 
z.FREE[@contents]; 
RETURN[shell]; 




DateFormatProc: FiieContainerSource.MultiAttributeFormatProc = 
begin 
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— If non- directory, show createdOn date. For directory, show last date modified 

(the last time anything was changed in directory) — 
template: xstring.ReaderBody 

XString.FromSTRING["<2>-<6>-<4> <8> : <9> : <10>"L]; 
XTime.Appencl[ 
displayString, 

IF attrRecord.isDi rectory THEN attrRecord.modif iedOn ELSE attrRecord. createdOn, 
©template]}; 
end; 

MakeColumnContents: procedure 

RETURNS [columnContents: long pointer to ContentSeq] = 

BEGIN 

dateSelections: NSFUe^Selections «- [interpreted: [ 

isDirectory: true, createdOn: true, modifiedOn: true]]; 

columnContents z.NEW[ContentSeq[NumberOfColumns]; 
columnContents[0] <r- FileContainerSource.NameColumn[]; 
columnContents[1] [multipleAttributes [attrs: dateSelections, formatProc: 
DateFormatProc]] ; 

RETURN [columnContents]; 
end; 

MakeColumnHeaders: procedure 

RETURNS [columnHeaders: long pointer to HeaderSeq] = 

BEGIN 

columnHeaders z.NEW[HeaderSeq[NumberOfColumns]]; 
columnHeaders[0] <— [ 
width: 367, 

heading: XString.FromSTRING["NAME"] ]; 
columnHeaders[1] [ 
width: 135, 

heading: xstring.FromSTRING["VERSION OF"] ]; 
return [columnHeaders]; 
end; 
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23.4 Index of Interface Items 

Item Page 

Create: procedure 1 

GetContainerSource: procedure 2 

GetContainerWindow: procedure 2 



FileContainerSource 



24.1 Overview 

FileContainerSource supports the creation of NSFile-backed container sources (see 
ContainerSource). It also provides facilities for specifying the columns that will be 
displayed for each item in the source. 

FileContainerSource implements all of the procedure types described in the 
ContainerSource interface, as well as all the procedures described below. 

24.2 Interface Items 



24.2.1 Creation 

Options: TYPE = record [ 
readonly: boolean ^ false]; 

Create: procedure [ 
file: NSFiie.Reference, 
columns: ColumnContents, 
scope: NSFiie.Scope [], 
options: Options ^ [] ] 
RETURNS [source: ContainerSource. Handle]; 

Creates a container source backed by file, which must be an NSFile with children, columns 
describes the information that should be displayed for each entry in the container, 
columns is copied by this procedure, so the client may release any storage associated with 
columns after calling Create, scope specifies the range of files that will be displayed, 
options specifies global information about the container source. Display formatting is 
managed by the container window. (See the ContainerWindow and FileContainerShell 
interfaces.) 



24.2.2 Specifying Columns 



When a file container source is created, columns may be specified. Each column represents 
information that will be displayed for each item. The container window requests the 
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columns one at a time in the form of strings. In a file container source, each column must 
be based on some combination of NSFile attributes. For each column, the creator of file 
container source specifies which attributes are required to format a string for that column 
and supplies a procedure that will be called with the specified attributes. When the files in 
the source are enumerated, the procedure for a particular column is called with the values 
of the specified attributes for each file, which should be used to generate the string for that 
file. 

ColumnContents: type ■ 

LONG DESCRIPTOR FOR ARRAY OF ColumnContentslnfo; 

ColumnContents describes a set of columns, where each column is some information that 
is displayed for each item in the container display. The columns are displayed in the order 
given by this array. 

ColumnType:TYPE = {attribute, extended Attribute, multipieAttributes}; 

ColumnContentslnfo: TYPE a record [ 
info: SELECT type: ColumnTypeFROM 
attribute « > [ 

attr: NSFile.AttributeType, 

formatProc: AttributeFormatProc <-nil], 
needsDataHandle: boolean «- false], 

extendedAttribute = > [ 

extendedAttr: NSFiie.ExtendedAttributeType, 

formatProc: AttributeFormatProc «-nil, 
extendedAttribute » > [ 

extendedAttr: NSFiie.ExtendedAttributeType, 

formatProc: AttributeFormatProc <-nil], 
multipieAttributes = > [ 

attrs: NSFile.Selections, 

formatProc: MultiAttributeFormatProc <-nil], 
enocase]; 

ColumnContentslnfo describes a single column of information that can be displayed for 
each item in a container display. Each column may be backed by one of three things: an 
NSFile interpreted attribute (the attribute variant), and NSFile extended attribute (the 
extendedAttribute variant), or some combination of several attributes (the 
multipieAttributes variant). The attribute and extendedAttribute variants both take a 
specification of what attribute is being described (attr and extendedAttr) and an 
AttributeFormatProc that is called to render the attribute as a string. If needsDataHandle 
s TRUE, then a valid Containee.DataHandle is passed to the format procedure as the 
containeeOata parameter, else the containeeOata parameter is nil. If the column needs a 
Containee.DataHandle in order to format it, then needsDataHandle should be true. This 
addition is for performance: obtaining a Containee.DataHandle requires an extra access to 
the file, thus slowing up the enumeration. The multipieAttributes variant is for columns 
that may require more than one attribute. (The typical example is the SIZE column in 
folders, in which some items display the numberOfChildren attribute and others display 
the sizelnPages attribute, depending on the isDirectory attribute.) attrs specifies all the 
attributes required for this column. formatProc is the procedure that will be called to 
format the column. 
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See the common types of columns provided below in the section on commonly used 
columns. 

AttributeFormatProc: type a procedure [ 
containeelmpi : Containee. Implementation, 
containeeData: Containee. OataHandle, 
attr: NSFiie. Attribute, 
displayString: xstring. Writer] ; 

When the container display mechanism displays a column that represents an NSFile 
attribute, it calls the AttributeFormatProc specified for that column, attr contains the 
attribute to be formatted for display. displayString is used to return a formatted string 
that represents the desired attribute, containeelmpi may be used to make calls on the 
underlying implementation of the item being displayed. 

MultiAttributeFormatProc: type = procedure [ 
containeelmpi: Containee. Implementation, 
containeeData: Containee. OataHandle, 

attrRecord: NSFiie. Attributes, lo/vg PO/zvrf ffroNSFile.AttributesRecord 
displayString: xstnng.Writer]; 

When the container display mechanism displays a column that represents multiple NSFile 
attributes, it calls the MultiAttributeFormatProc specified for that column. attrRecord 
contains the attributes to be formatted for display. displayString is used to return a 
formatted string that represents the desired attribute, containeelmpi may be used to 
make calls on the underlying implementation of the item being displayed. 

24.2.3 Operations on Sources 

Getltemlnfo: procedure [ 

source: ContainerSource. Handle, itemlndex: ContainerSource.ltemlndex] 
returns [file:NSFiie.Reference, type: NSFiie.Type]; 

Returns an NSFile. Reference and type for the specified item. 

Info: procedure [source: ContainerSource. Handle] 
returns [ 

file: NSFile. Reference, 
columns: ColumnContents, 
scope: NSFiie.Scope, 
options: Options]; 

The Info procedure returns information about a file container source; the information 
returned is the same information that was used to create the source (see the Create 
procedure). 

Isit: procedure [source: ContainerSource.Handle] returns [boolean]; 
Islt returns TRUE if source is a file container source. 

ChangeScope: procedure [source: ContainerSource.Handle, newScope: NSFiie.Scope]; 
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Allows the scope (passed in to Create) to be changed. A call to ChangeScope is typically 
followed by a source.ActOn[relistl, then a Containerwindow. Update. 

24.2.4 Commonly Used Columns 

These predefined procedures can be used in building a ColumnContents array. 

iconCoiumn: procedure 

RETURNS [attribute ColumnContentslnfo]; 

IconCoiumn represents a column with a small icon picture in it. The small picture is 
obtained from the contalneelmpl.smallPicture that is passed in. 

NameColumn: procedure 

RETURNS [attribute ColumnContentslnfo]; 

NameColumn represents a column with the file's name in it. 

SizeColumn: procedure 

RETURNS [multipleAttributes ColumnContentslnfo]; 

SizeColumn represents a column with the file's size in it, as follows: If the file has the 
isDirectory attribute, the numberOfChildren attribute is displayed with the label 
"Objects"; if the file does not have the isDirectory attribute, the sizelnPages attribute is 
displayed with the label "Disk Pages". 

DateColumn: procedure 

RETURNS [multipleAttributes ColumnContentslnfo]; 

DateColumn represents a column with the file's creation date in it, as follows: If the file 
has the isDirectory attribute, dashes ( — ) are displayed; if the file does not have the 
isDirectory attribute, the createDate attribute is displayed. 

24.3 Usage/Examples 

24.3.1 Example: Specifying Columns using FileContainerSource 

The following example presents the procedure MakeFolderLikeShell, which takes an 
NSFiie. Reference (Containee.DataHandle) and creates a file container shell with the 
number of columns dependent on some internal procedures. (See the ContainerSource 
interface for details on columns.) The columns use the predefined columns such as 
ContainerSource.NameColumn. 

Columns: type = {icon, name, version, nameAndVersion, size, createDate}; 
HeaderSeq: type = record [sequence coIs: cardinal of containerWindow.ColumnHeaderlnfoj; 
ContentSeq: TYPE = record! 

SEQUENCE COlS: CARDINAL OF FileContainerSource.ColumnContentSlnfoj; 
ColumnArray:TYPE « array {icon, name, version, size, date} OF cardinal; 
coiumnWidths: long pointer TO ColumnArray ^z.NEw[ColumnArray ♦-null]; 
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ClientsGenericProc: Containee.GenericProc = 
< <[atom: Atom.ATOM, 
data: containee.DataHandle, 
changeProc: Containee.ChangeProc <-nil, 
changeProcData: long pointer <- nil] 

RETURNS [long UNSPECIFIED] > > 
BEGIN 

SELECT atom FROM 
open = > RETURN [ 

MakeFolderLikeSheli [ 
data: data, 

changeProc: changeProc, 
changeProcData: changeProcData] ]; 



ENDCASE a > RETURN ( oldFolder.geneHcProc (atom, data] ]; 
end; 

FreeColumnContents: public procedure [columnContents: long pointer to ContentSeq] 
begin 

z.FREE[@columnContents]; 
end; 

FreeColumnHeaders: public procedure [columnHeaders: long pointer to HeaderSeq] = 
begin 

z.FREE[@columnHeaders]; 
end; 

MakeFolderLikeSheli: procedure [ 
data: Containee.DataHandle, 
changeProc: Containee.ChangeProc ^nil, 
changeProcData: long pointer <- nil] 
returns [shell: StarWindowShell.Handie] s { 
file: NSFiie.Reference; 

columnHeaders: long pointer to HeaderSeq «- MakeColumnHeaders(]; 
columnContents: long pointer to ContentSeq <- MakeColumnContents[]; 



mydata: Data <- z.new [DataObject <- [ 
cd: data, 

changeProc: changeProc, 
changeProcData : changeProcData]] ; 
isLocai: boolean; 

BEGIN enable 

unwind a > { 

z.FREE[@mydata]; 

FreeColumnHeaders [columnHeaders]; 
FreeCol u m nContents [col u m nContents] ; 

}; 
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shell <— FileContainerShell. Create [ 
file: file, 

column Headers: DESCRiPTOR[columnHeaclersl, 
columnContents: DESCRiPTOR(columnContents], 

regularMenultems: if ~isLocal then remoteRegularMenuitems else nil]; 

IF shell s NiLTHEN return [shell]; 

starWindowSheii.SetlsCioseLegalProc [shell. Closing]; 
Context.Create[context, mydata, DestroyContext, shell]; 
FreeColumnHeaders [columnHeaders]; 
FreeColumnContents [columnContents]; 
starwindowSheii.SetPreferredDims [ shell, [700, 0] ]; 

return [shell]; 
end; '- ENABLE 
} 

MakeColumnContents: public procedure returns [columnContents: long pointer to 
ContentSeq] = 
begin 

i: integer <--1; 

columnContents <— z.NEw[ContentSeq[CountColumns[]]]; 

IFSh0WlC0n[] THEN 

columnContents(i <— i + 1] <— FileContainerSource. lconColumn[l; 
— Procedures called below are not neccessary to the example. 
columnContents[i i + 1] «- 

IF ShowNameAndVersion[] 

THENFileContainerSourceExtra.NameAndVersionColumn[] 

E LSE FileContainerSource .NameColumn[]; 
IF ShowVersion[] then 

columnContents[i «-i + 1] <— FileContainerSourceExtra.VersionColumn[]; 
iFShowSize[] then 

columnContents(i <-i + 1] <-FiieContainerSource.SizeColumn[]; 
IF ShowCreateDate[] then 

columnContents[i <- i + 1] <-FileContainerSource.DateColumn[]; 
return [columnContents]; 
end; 
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24.4 Index of Interface Items 



Item Page 

AttributeFormatProc: type 3 

ChangeScope:pROCEDURE 3 

ColumnContents: type 2 

ColumnContentslnfo: type 2 

ColumnType:TYPE 2 

Create: procedure 1 

DateColumn: procedure 4 

Getltemlnfo: procedure 3 

ICOnColumn: PROCEDURE 4 

InfO: PROCEDURE 3 

Isit: PROCEDURE 3 

MultiAttributeFormatProc: type 3 

NameColumn: PROCEDURE 4 

Options: TYPE 1 

SizeColumn: PROCEDURE 4 
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25.1 Overview 

The FormWindow interface provides clients the ability to create and manipulate form 
items in a window. 

There are several types of items, each of which serves a different purpose and behaves 
differently for the user. All items except tagonly and command have a current value that 
can be obtained and set by the client and user. The user obtains the current value of an 
item by simply looking at it and sets the current value of an item by pointing at it 
appropriately with the mouse. The client obtains and sets the value of items by calling 
appropriate FormWindow procedures. 

A boolean item is an item with two states (on and off, or TRUE and FALSE). A boolean 
item's value is of type boole an. 

A choice item has an enumerated list of choices, only one of which can be selected at any 
point in time. A choice item's value is of type FormWindow. Choicelndex. 

A multiplechoice item is a choice item that can have an initial value of more than one 
choice selected, but any succeeding values can have only one choice selected. A 
multiplechoice item's value is of type long descriptor for array of cardinal. 

A text item is a user-editable text string. It contains nonattributed text only. A text item's 
value is of type xstring.ReaderBody. 

A decimal item is a text item that has a value of type XLReal. Number. 
An integer item is a text item that has a value of type long integer. 

A command item allows a user to invoke a command. When the user clicks over a 
command item, a client procedure is called. 

A tagonly item is an uneditable, nonselectable text string. 

A window item is a window that is a child of the FormWindow. It can contain whatever 
the client desires. A window item's value is a window. Handle. A client must provide its own 
TiP.NotifyProc and window display proc for the window item. 
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25.1.1 Creating a Form Window 



A client creates a FormWindow by calling FormWindow.Create. Create does not actually 
create a window, but rather it takes an already .existing window and turns it into a 
FormWindow. Windows are usually created by calling starWindowSheil.CreateBody. 

The client supplies a MakeltemsProc and optionally a LayoutProc to FormWindow.Create. 
Create calls these two client procedures, first the MakeltemsProc, then the LayoutProc. In 
the MakeltemsProc, the client creates the individual items in the form by calling 
FormWindow procedures that make items (see §25.1.2 and §25.2.2). In the LayoutProc, the 
client specifies where each created item should be positioned in the window by calling 
FormWindow procedures that specify layout (see the sections labeled Layout in this 
chapter). 



There is a procedure for making each type of item: MakeBooieanltem, MakeChoiceltem, 
MakeCommandltem, MakeOecimailtem, Makelntegerltem, MakeMuitipieChoiceltem, 
MakeTagOnlyltem, MakeTextltem, MakeWindowltem. Each item must have a unique 
"key", a FormWindow. ItemKey. This is a CARDINAL supplied by the client to each 
MakeXXXItem call. This key is then used in any future calls to manipulate that item, such 
as to get the value of the item. The key must be unique within the FormWindow. 

All items have some common characteristics and some type-unique characteristics. The 
common ones are described here. Every item can have a tag that will appear to the left of 
the item and a suffix that will appear to the right of the item. An item can have a box 
drawn around it or not. The default is to draw the box. Items can be read-only, that is the 
user cannot change the value of the item. Items can be visible or invisible, and invisible 
items can either take up white space in the window or not. See §25.2.2 for more details. 



Every item that has a value that the user can change (all except tagonly and command 
items) also has procedures for the client to get and set the value. These are; 



25.1.2 Making Form Items 



25.1.3 Getting and Setting Values 



GetBooleanitemValue 
GetChoiceltemValue 
GetDeci malltem Val ue 
GetlntegerltemValue 



SetBooleanltemValue 
SetChoiceltem Value 
SetDecimalltemValue 
SetlntegerltemValue 



DoneLookingAtlextltemValue 



GetMuitipleChoiceltemValue 
GetTextltemValue 



SetMultipleChoiceltemValue 
SetTextltemValue 



GetWi ndowltem Vai ue 
LoookAtTextltem Val ue 
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Note: All allocation of storage for values of items is handled by Form Window. The client 
need not keep copies of item values while the FormWindow exists. Obtaining the current 
value of an item is a simple call to one of the GetXXXItemValue procedures. This makes it 
easy to ensure that the internal value of an item is always in sync with the display. (See 
§25.2.3 for more details.) Fine Point: This storage allocation scheme is opposite to the one used by XDE's 
FormSW, where the client owns the storage for items. 

25.1.4 "Changed" BOOLEAN 

Every item that has a value that the user can change (all except tagonly, command, and 
window items) has a "changed" boolean associated with it. All items are created with this 
boolean set to false. FormWindow automatically sets this boolean to true whenever the 
user changes the item. This allows the client to determine which items have changed 
when, for example, the -user selects "Done" or "Apply" on a property sheet. The client is 
responsible for resetting the changed boolean to false by calling ResetChanged or 
ResetAllChanged after examining the changed boolean with HasBeenChanged or 
HasAnyBeenChanged. See §25.2.1 for more detail. 

Boolean and choice items can have a client-supplied procedure that will be called 
whenever the item's value changes (see BooleanChangeProc and ChoiceChangeProc in 
§25.2.1 and 25.2.2. The client may also supply a GlobalChangeProc that will be called 
whenever any item changes (see §25.2.1). 

25.1.5 Visibility 

Each item is either displayed in the form window or not. If an item is displayed in the form 
window, it is visible. If an item is not currently displayed, it is either invisible or 
invissbleGhost. If it is invisible, it does not take up any space on the screen, that is any 
items below it move up to take its screen space. If an item is invisibleGhost, the space that 
it would occupy were it visible is white on the screen. An item's visibility can be changed 
at any time by calling SetVisibility (see §25.2.5.) 

25.1.6 Layout 

The exact layout of items in a form window is done by calling various layout procedures 
after creating the items to be laid out. If an item is not explicitly laid out, it will not appear 
in the form window at all. A DefaultLayout procedure is provided that places each created 
item on a separate line. 

A form window consists of horizontal lines with zero or more items on each line. Each line 
may be a different height. Any desired vertical spacing may be accomplished by using 
appropriate heights for lines. Any desired horizontal spacing may be accomplished by 
using appropriate margins between items. Items may be lined up horizontally by using 
TabStops. Lines are created by calling AppendLine or InsertLine. Items are placed on a 
line by calling Appendltem or Insertltem. (See §25.2.6 for more detail.) 
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25.2 Interface Items ^ 
25.2.1 Creating a Form Window, etc. 



Create: procedure [ 

window: window. Handle, 
makeltemsProc: MakeltemsProc, 
layoutProc: LayoutProc «- nil, 
windowChangeProc: GlobalChangeProc <-nil, 
minDimsChangeProc: MinDimsChangeProc <— nil, 
zone: uncounted zone nil, 
clientData: long pointer nil ]; 

Create takes an ordinary window and makes it a form window. 

window is a window created by the client. Windows are usually created by calling 
StarWindowShell.CreateBody. 

makeltems is a client-supplied procedure that is called to make the form items in the 
window, makeltems should call various FormWindow.MakeXXXItem procedures (see 

§25.2.2). Fine Point: makeltems is not called after Create returns, so makeltems can be a nested procedure. 

layoutProc is a client-supplied procedure that is called to specify the desired position of the 
items in the window. layoutProc is called after makeltems has been called. layoutProc 
should call various layout procedures (see §25.2.6), such as AppendLine and Appendltem. 
If the default is taken, the DefaultLayout of one item per line will be used. 

windowChangeProc is the global change proc for the entire window. Any time any item in 
the window changes, this procedure is called. 

zone is the zone from which storage for the items will be allocated. FormWindow uses a 
private zone if none is supplied. 

clientData is passed to makeltems, layoutProc, and windowChangeProc when called. 
May raise Error[alreadyAForm Window]. 

DefaultLayout: LayoutProc; 

The default for the Create layoutProc parameter. Specifies a layout of one item per line. 
Destroy: procedure [window: window.Handie]; 

Destroy destroys all FormWindow data associated with window, turning it back into an 
ordinary window. All form items are destroyed, but the window itself is not destroyed. 
May raise Error[notAFormWindowl. 

GetClientData: procedure [window: window. Handle] 
returns [clientData: long pointer]; 

GetClientData returns the clientData that was passed to Create. May raise 
Error[notAForm Window] . 

GlobalChangeProc: type s procedure [ 
window: window. Handle, 
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item: ItemKey, 

calledBecauseOf: ChangeReason, 
clientData: long pointer]; 

The client may supply a GlobaiChangeProc to Create. Any time the value of any item in 
the window is changed, the GlobaiChangeProc is called with the key of the item that was 
changed. If more than one item was changed at one time (such as by a client call to 
FormWindow.Restore), nullltemKey will be passed in and the client must examine the 
"changed" boolean of all items to see what was changed (see §25.2.4). calledBecauseOf 
indicates what kind of action caused the GlobaiChangeProc to be called. clientData is the 
LONG POINTER that was passed to Create. 

GetGiobalChangeProc: procedure [window: window. Handle] 
RETURNS [proc: GlobaiChangeProc]; 

GetGiobalChangeProc returns the GlobaiChangeProc that was passed to Create. May 
raise Error[notAFormWindow]. 

SetGlobalChangeProc: procedure [window: window.Handie, 
proc: GlobaiChangeProc] returns [old: GlobaiChangeProc]; 

SetGlobalChangeProc changes the GlobaiChangeProc that was passed to Create. May 
raise Error[notAFormWindow]. 

MinDimsChangeProc: type « procedure [window: window.Handie, 
old, new: Window. Dims]; 

Whenever the minimum dimensions of the FormWindow change, the client supplied 
MinDimsChangeProc is called. This is useful for form windows that are nested as window 
items inside another outer form window. Whenever the dimensions of the nested form 
window change (due to items being made visible or invisible or a text item growing or 
shrinking or new items being added or...), the client that created the window item and the 
nested form window can be called so that it can make the window item bigger or smaller 
for the nested form window to be completely visible. See also NeededDims. 

GetZone: procedure [window: window.Handie] 
returns [zone: uncounted zone]; 

GetZone returns the zone associated with the FormWindow. May raise 
Error[notAForm Wi ndow] . 

Isit: procedure [window: window.Handie] returns [yes: boolean]; 

Isit is used to determine if a window is a form window. If window was made into a form 
window by calling FormWindow. Create, then Isit returns TRUE, else false. 

LayoutProc:TYPE = procedure [window: window.Handie, clientData: long pointer]; 

The client supplies a LayoutProc to Create to specify the location of items created by the 
MakeltemsProc. See §25.2.6 for details of layout. 
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MakeltemsProc: type =» procedure [ 
window: window. Handle, 
clientData: long pointer]; 

The client supplies a MakeltemsProc to Create to make the form items in the window, 
Create will call the client's MakeltemsProc, and it should call various MakeXXXItem 
procedures (see §25.2.2) to make the items, window should be passed to the various 
MakeXXXItem. clientData is the same as that passed to Create. Fine point for clients of 

PropertySheet: clientData can be passed to PropertySheet.Create and will be passed on to FormWindow.Create 
and the MakeltemsProc. 

NeededDims: procedure [window: window.Handle] 

RETURNS [WIndow.Dims]; 

NeededDims returns the minimum dimensions required for a window to hold all the 
currently visible items in the form. 

NumberOfltems: procedure [window: window.Handle] returns [cardinal]; 

NumberOfltems returns the current number of form items in window. This count will 
include visible and invisible items. This is useful for clients that create additional items 
dynamically after the form has been created. May raise Error[ notAFormWindow]. 

Repaint: procedure [window: window.Handle]; 

Repaint causes the entire form to be repainted. This is used in conjunction with the 
SetXXXItem Value, SetVisibility, Appendltem, and Insertltem procedures. All these 
procedures take a repaint: boolean parameter. To minimize screen flashing while 
changing several items at the same time, the client may call these procedures with repaint 
s false, then call FormWindow. Repaint. The form window will not be repainted until 
Repaint is called. Warning: After calling any procedure with repaint = false, 
Form Window. Re paint must be called. Otherwise, the screen will be inconsistent with the 
internal values. May raise Error[notAFormWindow]. 

25.2.2 Making Form Items, etc. 

Create procedures are provided for each type of item. These MakeXXXItem routines are 
used to originally create items in a form window as well as to add items to an existing 
window. 

A number of parameters to each MakeXXXItem procedure are identical and are described 
here, rather than with each procedure. If all of the defaults are taken for an item, it will be 
boxed, with no tags and not read-only. All of these may raise Error[notAFormWindow]; 

window is the form window the item is contained in. It should be the same as the window 
passed to the client's MakeltemsProc. 

myKey is a client-defined key (ItemKey) for the item. The item key uniquely identifies the 
item and should be used to make calls on other FormWindow procedures, such as 
GetXXXItemValue. Caution: The key must be unique within this form window. 

tag is the text to be displayed before (to the left of) the item on the same line. (To put a tag 
on a separate line, use MakeTagOnlyltem.) 



i 

i 
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suffix is the text to be displayed after (to the right of) the item on the same line. 

visibility indicates whether the item should be displayed on the screen. 

boxed indicates whether the item should have a box drawn around it or not. 

readonly a true indicates that the item can not be edited by the user. The item can still be 
changed by calling a SetXXXItemValue procedure. 

ItemKey: type a cardinal; 

ItemKey uniquely identifies an item. An ItemKey is supplied by the client whenever an 
item is made (MakeXXXItem) and should be used thereafter to identify the item to 
FormWindow, such as then calling GetXXXItem Value or SetVisibility. 

ItemType: type » machine dependent {choice(O), multiplechoice, decimal, integer, 
boolean, text, command, tagonly, window, last(15)}; 

There are several types of items, each of which serves a different purpose and behaves 
differently for the user. All items except tagonly and command have a current value that 
can be obtained (GetXXXItemValue) and set (SetXXXItemValue). 

A choice item has an enumerated list of choices, only one of which can be selected at any 
point in time. A choice item's value is of type FormWindow.Choicelndex. 

A multiplechoice item is a choice item that can have an initial value of more than one 
choice selected, but any succeeding values can have only one choice selected. A multiple 
choice item's value is of type long descriptor for array of cardinal. 

A text item is a user-editable text string, and contains only nonattributed text. A text 
item's value is of type xstring.ReaderBody. 

A decimal item is a text item that has a value of type XLReal. Number. 
An integer item is a text item that has a value of type long integer. 

A boolean item is an item with two states (on and off, or TRUE and FALSE). A boolean 
item's value is of type boolean. 

A command item allows a user to invoke a command. When the user clicks over a 
command item, a client procedure is called. 

A tagonly item is an uneditable, nonselectable text string. 

A window item is a window that is a child of the FormWindow and can contain whatever 
the client desires. A window item's value is a window. Handle. A client must provide its own 
tip. Notify Proc and window display procedure for the window item. 

nullltemKey: ItemKey; 

nullltemKey is used to indicate no item. 

25.2.2.1 Boolean Items 

MakeBooleanitem: procedure [ 
window: window. Handle, 
myKey: ItemKey, 
tag: xstring.Reader <- nil. 
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suffix: xstring.Reader 4-Niu 
visibility: Visibility <- visible, 
boxed: boolean <- true, 
readonly: boolean <- false, 
changeProc: BooleanChangeProc 
label: BooleanltemLabel, 
initBoolean: boolean <- true]; 



NIL, 



MakeBooleanltem creates a boolean item. A boolean item value is of type boolean. When 
the value is true, the item is highlighted. When FALSE, it is not highlighted. When the user 
clicks over the label part of a boolean item, the value toggles. 




Unhighlighted boolean item, value = FALSE 



changeProc is a client-supplied procedure that will be called whenever the value of the 
item changes. 

label is the string or bitmap that the user points at to toggle the item's value. If label is a 
string, the string is copied. If label is a bitmap, the bits are not copied, so the client must 
ensure that the bitmap pointer is valid for the lifetime of the form window. 

initBoolean is the initial value of the item. 

May raise Error[notAFormWindow, duplicateltemKey]. 

BooleanltemLabel: type = record [ 

var: select type: BooleanltemLabelType from 
string a > [string: xstring.ReaderBody], 
bitmap * > [ bitmap: Bitmap] 
endcase]; 

BooleanltemLabelType: type = {string, bitmap}; 

A BooleanltemLabel is passed to MakeBooleanltem. It is the part of the item that the user 
points at and is or is not highlighted, depending on the value of the item. A label may be 
either a string or a bitmap. (See §25.2.8 on Miscellaneous TYPEs for the definition of 
Bitmap). If label is a string, the string is copied. If label is a bitmap, the bits are not copied, 
so the client must ensure that the bitmap pointer is valid for the lifetime of the formi 
window. 



BooleanChangeProc: type a procedure [ 
window: Window. Handle, 
item: ItemKey, 

calledBecauseOf: ChangeReason, 
newValue: boolean]; 

The client may provide a BooleanChangeProc to MakeBooleanltem. Whenever the item's 
value changes (true to false or false to true), this procedure is called, window is the form 
window that the item is in. item is the key of the boolean item to which this 
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BooleanChangeProc is attached. calledBecauseOf indicates what kind of action caused the 
change proc to be called. newValue is the vew value of the item. The item will already 
have the new value when this procedure is called. 

Caution: If a BooleanChangeProc does a SetXXXItem Value, the client should take 
extreme care to prevent infinite recursion. (See §25.3.1.) 



25.2.2.2 Choice Items 



MakeChoiceltem: procedure [ 
window: wfndow.Handle, 
myKey: ItemKey, 
tag: xstring. Reader <- nil, 
suffix: xstring.Reader «-nil, 
visibility: Visibility <- visible, 

boxed: BOOLEAN*- TRUE, 

readonly: boolean <- false, 
values: Choiceltems, 
initChoice: Choicelndex, 
fuliyDispiayed: boolean «- true, 
verticailyDisplayed: boolean «- false, 
hintsProc: ChoiceHintsProc<-NiL, 
changeProc: ChoiceChangeProc <- nil, 
outlineOrHighlight: OutlineOrHighlight highlight]; 

MakeChoiceltem creates a choice item.. A choice item is an enumerated list of choices, only 
one of which can be selected at any time . The choices can be displayed to the user as either 
strings or bitmaps, or some of each. The current choice is highlighted. When the user 
clicks on a choice, it becomes the current choice and is highlighted. Each choice has a 
client-defined Choicelndex associated with it that uniquely identifies that choice. The 
value of a choice item is of type Choicelndex. 

values is the list of all the possible choices. An indication of where to wrap the display 
around to the next line can be made by specifying a wraplndicator variant in the 
appropriate place in the values array. If a choice is a string, the string is copied. If a choice 
is a bitmap, the bits are not copied, so the client must ensure that the bitmap pointer is 
valid for the lifetime of the form window. 

initChoice is the value of the initial choice. 

fuliyDispiayed indicates whether all the choices should be displayed or not. If 
fuliyDispiayed a true, all the choices are displayed. If fuliyDispiayed = false, only the 
current choice is displayed, with the rest of the choices being accessed via a popup menu. 

verticailyDisplayed indicates whether the choices should be displayed vertically or 
horizontally. If fuliyDispiayed = false, the value of verticailyDisplayed is ignored. Any 
wraplndicators are skipped over when choices are displayed vertically. 

If hintsProc is supplied, it is called to make a popup hint menu. If the default is taken, the 
form window will make a hint menu with all choices. Note: Since menus can only contain 
strings (not bitmaps), a bitmap choice will appear in the hints menu as a number 
indicating the choice's position. Note: This is not the same as the Choicelndex for that 
choice. 
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If changeProc is supplied, it is called whenever the choice changes. 

May raise Error[notAFormWinclow,duplicateltemKey, invalidChoiceNumber]. 

OutlineOrHighlight: type a {outline, highlight}; 

Normally the selected choice for a choice item is indicated by highlighting the choice. The 
OutlineOrHighlight parameter allows the selected choice to be indicated by outlining the 
choice with a black box. This is intended to support the Shading choice item on, for 
example, the triangle and ellipse property sheets in the ViewPoint editor. 

Choiceltems: type = long descriptor for array Choicelndex of Choiceltem; 

Choiceltems is the list of possible choice for a choice item. A Choiceltems array is passed to 
MakeChoiceltem. The choices are displayed in the order they appear in the Choiceltems 
array. 

Choiceltem: TYPE = record [ 

var: select type: ChoiceltemType from 
string s > [ 

choiceNumber: Choicelndex, 

string: xstring.ReaderBody], 
bitmap = >[ 

choiceNumber: Choicelndex, 

bitmap: Bitmap], 
wrapindicator « > null]; 

ChoiceltemType: TYPE = {string, bitmap, wrapindicator}; 

Choicelndex: type ■ cardinal [ 0.. 377778 ]; 

A choice item consists of an array of choices (Choiceltems). Each choice (Choiceltem) 
consists of a unique number that identifies the choice (Choicelndex) and either a string or 
a bitmap to display to the user. In addition, the Choiceltems array can contain a 
wrapindicator wherever the client desires the choices be wrapped around to begin another 
line of choices. A wrapindicator Choiceltem is not a real choice and serves only as 
additional layout information for the FormWindow. If Choiceltem is a string, the string is 
copied. If Choiceltem is a bitmap, the bits are not copied, so the client must ensure that the 
bitmap pointer is valid for the lifetime of the FormWindow. 

The client must construct a Choiceltems array before calling MakeChoiceltem. This can 
be simplified if all the choices are strings by using the FormWindowMessageParse 
interface. This allows all the choices for a choice item to be stored as a single XMessage 
with embedded syntax indicating individual choice strings and choice numbers. (See 
FormWindowMessageParse for more detail.) 

ChoiceChangeProc: type = procedure [ 
window: window. Handle, 
item: ItemKey, 

calledBecauseOf: ChangeReason, 
oldValue, newValue: Choicelndex]; 
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The client may provide a ChoiceChangeProc to MakeChoiceltem. Whenever the choice 
changes, this procedure is called, window is the form window that the item is in. item is 
the key of the choice item to which this ChoiceChangeProc is attached. calledBecauseOf 
indicates what kind of action caused the change proc to be called. oidValue and newValue 
correspond to the choice numbers assigned to the choices in MakeChoiceltem. The item 
will have the new value when this procedure is called. 

Caution: If a ChoiceChangeProc does a SetXXXItemValue, the client should take extreme 
care to prevent infinite recursion. See §25.3.1, Calling ChangeProcs. 

ChoiceHintsProc: TYPE a procedure [ 
window: window. Handle, 
item: ItemKey] 

RETURNS [ 

hints: long descriptor for array of Choicelndex, 
f reeH i nts : FreeChoiceH i ntsProc] ; 

FreeChoiceHintsProc: type a procedure! 
window: window.Handle, 
item: ItemKey, 

hints: long descriptor for array of Choicelndex]; 

The client may provide a ChoiceHintsProc to MakeChoiceltem. Whenever the user points 
at the mouse menu for a choice item, this procedure is called and the hints returned are 
used to construct a popup menu that is displayed. If the user selects one of the choices from 
the popup menu, that choice becomes the current choice. 

window is the form window that the item is in. 

item is the key of the choice item to which this ChoiceHintsProc is attached. 

hints is an array of choice numbers for the choices that the client wants to appear in the 
menu. This allows a client to show a subset of all the choices to the user for situations in 
which not all the choices make sense. 

freeHints is a procedure that will be called after the hint menu has been taken down to 
allow the client to free any storage that was allocated when creating the hints array. 

MakeMultipleChoiceltem: procedure [ 
window: window.Handle, 
myKey: ItemKey, 
tag: xstring.Reader <- nil, 
suffix: xstring.Reader <-nil, 
visibility: Visibility <- visible, 
boxed: boolean <- true, 
readonly: boolean*- false, 
values: Choiceltems, 

initChoice: long descriptor for array of Choicelndex, 
verticallyDisplayed: boolean false, 
hintsProc: ChoiceHintsProc <-NiL, 
changeProc: MultipleChoiceChangeProc ^niilI; 

May raise ErrorfnotAFormWindow, duplicateltemKey]. 
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MuitipleChoiceChangeProc: type = procedure [ 
window: window.Handle, 
item: ItemKey, 

calledBecauseOf: ChangeReason, 

oldValue: long descriptor for array of Choicelndex, 

newVaiue: long descriptor for array of Choicelndex]; 

A multiple choice item is identical to a choice item, except that it may have more than one 
initial value. See MakeChoiceltem above for details of choice items. A multiple choice 
item is useful for showing the properties of a heterogenous selection, such as the font 
property of a text selection that has more than one font. 

25.2.2.3 Command Items 

MakeCommanditem: procedure [ 
window: window.Handle, 
myKey: ItemKey, 
tag: xstring. Reader nil, 
suffix: xstring.Reader«-NiL, 
visibility: Visibility ^visible, 
boxed: boolean <- true, 
readonly: boolean <- false, 
commandProc: CommandProc, 
commandName: xstring.Reader, 
clientData: long pointer nil]; 

Creates a command item. A command item allows a user to invoke a command. When the 
user clicks over the commandName, commandProc is called. If boxed is true, the 
commandName appears with a rounded corner box drawn around it (rather than a square- 
cornered box, to distinguish a command item from a boolean item). May raise 
Error[notAFormWindow, duplicateltemKey]. 

CommandProc: type ■ procedure [ 
window: window.Handle, 
item:ltemKey, clientData: long pointer]; 

A CommandProc is supplied by the client to MakeCommanditem. It is called whenever 
the user selects the command item, window is the FormWindow that the item is in. item 
is the key of the command item to which this CommandProc is attached. 

25.2.2.4 Tagonly items 

MakeTagOnlyitem: procedure [ 
window: window.Handle, 
myKey: ItemKey, 
tag: xstring.Reader, 
visibility: Visibility <- visible]; 

Creates a tagonly item. Tagonly items are displayed as uneditable, nonselectable 
text.May raise Error[notAForm Window, duplicateltemKey]. 
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25.2.2.5 Text and Number Items 

MakeTextltem: procedure [ 
window: window. Handle, 
myKey: ItemKey, 
tag: xstring. Reader <- nil, 
suffix: xstring.Reader <-NiL, 
visibility: Visibility visible, 
boxed: boolean «- true, 
readonly: BOOLEAN*- FALSE, 
width: CARDINAL, -- in screen dots 
initString: xstnng. Reader «- nil, 
wrapUnderTag: boolean*- false, 
passwordFeedback: boolean*- false, 
hintsProc: TextHiintsProc*-NiL, 
nextOutOfProc: NextOutOfProc nil, 
SPEC! ALKey board: BiackKeys.Keyboard <-nil]; 



Creates a text item. Text items are user-editable text strings. The value of a text item is of 
type xstring.ReaderBody. The user may select text, extend the selection, insert text, delete 
text, move and copy text, etc. Text items are fixed width but may grow and shrink 
vertically as the user enters and deletes text. A text item will contain nonattributed text 
only. FormWindow handles all storage allocation for the backing string. 

width is the number of screen dots wide that the item should be. The item may grow 
arbitrarily long as the user enters text, but it will always retain the same width. 

initString is the initial string to place in the text item. The bytes are copied by 
FormWindow. 

wrapUnderTag specifies whether any text wider than the width of the text item should 
appear underneath the tag (wrapUnderTag = true) or start at the left edge of the text 
item (wrapUnderTag = false). Note: This feature is not yet implemented. 

passwordFeedback indicates that the text should be displayed in an unreadable form 
rather than as normal characters. The correct value of the string is maintained internally, 
so that a call to GetTextltem Value will return the proper value. 

If hintsProc is supplied, it is called to make a list of strings to be displayed to the user as a 
popup hint menu. (See TextHintsProc below.) 

If nextOutOfProc is supplied, it is called when the user presses the NEXT key while the 
input focus is in this text item. This gives the client an opportunity to create more text 
items. After calling the nextOutOfProc or if no nextOutOfProc is supplied, the NEXT key 
causes the selection and input focus to move to the next text or window item in the form. 
See NEXT key in this chapter for further explanation. 

If SPECIALKeyboard is supplied, it allows clients to make a special keyboard available to 
the user when typing into a text or number field. 

May raise Error[notAFormWindow, duplicateltemKey]. 



MakeOecimalltem: procedure 
window: window. Handle, 
myKey: ItemKey, 
tag: xstring. Reader <- nil. 
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suffix: xstring. Reader <- NIL, 
visibility: Visibility <- visible, 
boxed: boolean ^true, 
readonly: boolean ♦-false, 
signed: boolean <- false, 
width: CARDINAL, -- in screen dots — 
initDecimal: XLReai. Number XLReal.zero, 
wrapUnderTag: boolean*- false. 
hintsProc: TextHintsProc<-NiL, 
nextOutOfProc: NextOutOf Proc <- nil, 
displayTemplate: xstring.Reader nil, 
SPECIALKeyboard: Black Keys. Keyboard <-nil]; 

Creates a decimal item. A decimal item is a text item that has a value of type 
XLReal.Number. (See MakeTextltem above for details of text items.) The user can type any 
text into the decimal item, but when the client calls GetDecimalltemValue to retrieve the 
value, FormWindow converts the string to XLReal.Number. initDecimal is the initial 
decimal value to place in the item. displayTemplate parameter is defined as in the 
XLReai. PictureReal. XLReai.PictureReal is used to display the value of the decimal item. The 
client may provide a keyboard interpretation with the SPECIALKeyboard parameter (see 
Chapter 8, §2.1 ). May raise ErrorfnotAFormWindow, duplicateltemKey]. 

Makelntegerltem: procedure [ 
window: window. Handle, 
myKey: ItemKey, 
tag: xstring. Reader <- nil, 
suffix: xstring. Reader «-nil, 
visibility: Visibility <— visible, 
boxed: boolean <- true, 
readonly: boolean*- false, 
signed: boolean ♦-false, 
width: cardinal, — in screen dots — 
initlnteger: long integer*- 0, 
wrapUnderTag: boolean*- false, 
hintsProc: TextHintsProc«-NiL, 
nextOutOfProc: NextOutOfProc *- nil, 
SPECIALKeyboard: BlackKeys.Keyboard «-nil]; 

Creates an integer item. An integer item is a text item that has a value of type long 
INTEGER. (See MakeTextltem above for details of text items.) The user can type any text 
into the integer item, but when the client calls GetlntegerltemValue to retrieve the value, 
FormWindow converts the string to a LONG INTEGER, initlnteger is the initial number to 
place in the item. The client may provide a keyboard interpretation with the 
SPECIALKeyboard parameter (see Chapter 8, §2.1). May raise Error[ notAFormWindow, 
duplicateltemKey]. 

TextHintAction: TYPE = {replace, append, nil}; 

TextHintsProc: TYPE = procedure [ 
window: window. Handle, 
item: ItemKey] 

RETURNS [ 
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hints: long descriptor for array of xstring.ReaderBody, 
freeHints: FreeTextHintsProc, 
hlntAction: TextHint Action <- replace]; 

FreeTextHintsProc: type = procedure [ 
window: window.Handle, 
item: ItemKey, 

hints: long descriptor for array of xstHng.ReaderBody]; 



The client may provide a TextHintsProc to Mai<eTextltem, Mal<eDecimalltem, and 
Makelntegerltem. Whenever the user points at the mouse menu for a text item, this 
procedure is called and the hints returned are used to construct a popup menu that is 
displayed. 

When the user selects one of the strings from the popup menu, one of three things will 
happen, depending on the hintAction returned by the TextHintsProc. If hintAction = 
replace, the selected string will replace the current value of the text item. If hintAction = 
append, the selected string will be appended to the current value of the text item. If 
hintAction = nil, the current value of the text item will not change. hintAction = nil is 
useful for displaying "help-like" information to the user for text items that do not have a 
finite number of possible values, such as a file name. 

freeHints is a procedure that will be called after the hint menu has been taken down to 
allow the client to free any storage that was allocated when creating the hints array. 



25.2.2.6 Window Items 

MakeWindowltem: procedure [ 
window: window.Handle, 
myKey: ItemKey, 
tag: xstHng. Reader «- nil, 
visibility: Visibility <- visible, 
boxed: boolean <~ true, 
size: window.Dims, 
nextlntoProc: NextlntoProc«-NiLl 
returns [clientWindow: window.Handle]; 



Creates a window item. A window item is a window (window.Handle) that is a child of the 
FormWindow and can contain anything the client desires. A window with dimensions size 
is created and returned as clientWindow. It is expected that the client will associate a 
display proc (see window.SetDisplayProc) and a tip. Notify Proc with the window. The 
window may be treated just like any other window, except FormWindow. SetWindowltemSize 
must be used to change the size of the window rather than calling window. SlideAndSize 
directly. This allows FormWindow to move any other items, if necessary, to accomodate 
the different-sized window item. 

If nextlntoProc is supplied, it is called when the user presses the NEXT key in an item just 
before this window item. This gives the window item an opportunity to gain control of the 
NEXT key by setting the input focus to be the window item's window. The window item 
may then retain control of the NEXT key within the window item. When the window item 
no longer wants to process the NEXT key (for instance, when the NEXT key should move the 
selection outside the window item), the window item client must call 
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FormWindow.TakeNEXTKey, which returns the next key processing to the form window. 
(See §25.2.10 for an explanation of the NEXT key.) 

May raise Error(notAForm Window, duplicateltemKey]. 

SetWindowltemSize: procedure [ 
window: window. Handle, 
windowltemKey: ItemKey, 
newSize: window.Oims]; 

SetWindowltemSize should be used to change the size of a window item's window. The 
client should never call Window.SlideAndSize directly. Any items below the window item 
are moved down or up to accommodate the new dimensions, window is the form windov/ 
that the window item is in. windowltemKey must be the key of a window item. newSize 
indicates the new dimensions. May raise Error[ notAForm Window, invalidltemKey, 
wrongltemType] . 



25.2.2.7 Destroying Items 



Destroyltem: procedure [ 
window: Window. Handle, 
item: ItemKey, 
repaint: boolean <«-true]; 



Destroyltem destroys item. Most clients will not need to use this procedure, since 
Form Window. Destroy destroys all the items in the FormWindow. May raise 
Error[notAFormWindow, invalidltemKey]. 

Destroyltems: procedure [ 
window: Window. Handle, 
item: long descriptor for array of ItemKey, 
repaint: boolean <-true]; 

Destroyltems destroys several items at once. Most clients will not need to use this 
procedure, since Form window. Destroy destroys all the items in the FormWindow. May raise 
ErrorfnotAFormWindow, invalidltemKey]. 



25.2.3 Getting and Setting Values 

The client may examine or change the value of an item. All GetXXXItem procedures 
return the current value of an item. All SetXXXItem procedures take a given new value 
and change the value internally, as well as updating the screen if necessary. 

In all these procedures, window is the FormWindow the item is in. item uniquely 
identifies the item to get/set the value of. 

Note: There are two ways to get the value of a text item. GetTextltemValue copies the 
bytes of the string so that the storage for the returned value is owned by the client. 
LookAtTextltem Value simply returns a pointer to the FormWindow-owned backing 
string. This value is therefore read-only and must be released when the client is done 
examining it by calling DoneLookingAtTextltemValue. 
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All of these may raise Error| notAFormWindow, invalidltemKey, wrongltemType]. 



25.2.3.1 Getting Values 



GetBooleanltemValue: procedure [ 
window: window. Handle, 
item: ItemKey] 
RETURNS [value: boolean]; 

GetChoiceltemValue: procedure [ 
window:wmdow.Handie, 
item: ItemKey] 
returns [value: Choicelndex]; 

GetOecimalltemValue: procedure [ 
window: window. Handle, 
item: ItemKey] 

returns [value:xLReai.Number]; 

May raise XLReal. Error [notANumber]. 

GetlntegerltemValue: procedure [ 
window: window. Handle, 
item: ItemKey] 
RETURNS [value: long integer]; 

May raise xstring.lnvalidNumber or XString. Overflow. 

GetMultipleChoiceitemVaiue: procedure [ 
window: window. Handle, 
item: ItemKey, zone: uncounted zone] 
returns [values: long descriptor for array of Choicelndex]; 

The zone parameter is added. The storage for the DESCRIPTOR will be allocated out of zone 
and the storage must be freed by the client. 

GetTextltemValue: procedure [ 
window: window. Handle, 
item: ItemKey, 
zone: uncounted zone] 
RETURNS [value: xstring.ReaderBody]; 

GetTextltemValue copies the string. Storage for the bytes is allocated out of zone. The 
client should free the storage using xstring.FreeReaderBytes and zone. 

GetWindowitemValue: procedure [ 
window: window. Handle, 
item: ItemKey] 

returns [value: window. Handle]; 

LookAtTextltemValue: procedure [ 
window: window. Handle, 



25-17 



Form Window 



item: ItemKey] 

RETURNS [value: xstnng.ReaderBody]; 

DoneLookingAtTextltemValue: procedure [ 
window: window.Handle, 
item: ItemKey]; 



LookAtTextltemValue does not copy the string but returns a pointer to it. value should not 
be changed by the client. Clients using LookAtTextltemValue must call 
DoneLookingAtTextltemValue when done examining it. During the time between these 
calls, if another client calls LookAtTextltemValue or SetTextltem Value for the same text 
item, the second client's process will wait. 

GetNextAvailableKey: procedure [window: window.Handle] 
returns [key: ItemKey]; 

Returns the next available item key: ivlAX[usedKeys]+ 1. 



25.2.3.2 Setting Values 



All the SetXXXItem procedures take a repaint: boolean. If repaint = true and the item is 
currently visible, it will be repainted with the new value. If repaint = false, the item will 
not be repainted until Formwindow. Re paint is called. This allows the client to change the 
values of several items at once without the screen flashing for each item. Warning: After 
calling any procedure with repaint = false. Form window. Re paint must be called. .^tlik. 
Otherwise, the screen will be inconsistent with the internal values. 

Caution: If a change proc does a SetXXXItem Value, the client should take extreme care to 
prevent infinite recursion. (See §25.3.1.) 



SetBooleanltemValue: procedure [ 
window: window.Handle, 
item: ItemKey, 
newValue: boolean, 
repaint: boolean ^true]; 

SetChoiceltemValue: procedure [ 
window: window.Handle, 
item: ItemKey, 
newValue: Choicelndex, 
repaint: boolean <-true]; 



May raise FormWindow.Error[invalidChoiceNumber]. 



SetOecimalltemValue: procedure [ 
window: window.Handle, 
item: ItemKey, 
newValue: XLReai. Number, 
repaint: boolean <-true]; 

SetlntegerltemValue: procedure [ 
window: window.Handle, 
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item: ItemKey, 
newVaiue: long integer, 
repaint: boolean <-true]; 

SetMultipleChoiceltemValue: procedure [ 
window: Window. Handle, 
item: ItemKey, 

newValue: long descriptor for array of Choiceindex, 
repaint: boolean <-true]; 

May raise FormWlndow.Error[invalidChoiceNumberl. 

SetTextltemValue: procedure [ 
window: window. Handle, 
item: ItemKey, 
newValue: xstring. Reader, 
repaint: boolean <-true]; 



25.2.4 "Changed" BOOLEAN 

Every item that has a value that the user can change (all except tagonly and command 
items) has a "changed" boolean associated with it. All items are created with this boolean 
set to FALSE. FormWindow automatically sets this boolean to true whenever the user 
changes the item. This allows the client to determine which items have changed when, for 
example, the user selects "Done" or "Apply" on a property sheet. The client is responsible 
for resetting the changed boolean to false by calling ResetChanged or ResetAllChanged 
after examining the changed boolean with HasBeenChanged or HasAnyBeenChanged. 

HasAnyBeenChanged: procedure [ 
window: Window. Handle] 
RETURNS [yes: boolean]; 

HasAnyBeenChanged returns true if any item's changed boolean is true. May raise 
Error[notAFormWindow]. 

HasBeenChanged: procedure [ 
window: window. Handle, 
item: ItemKey] 
RETURNS [yes: boolean]; 

HasBeenChanged returns true if the user has changed item. The client may reset the 
changed boolean to false by using ResetChanged or ResetAllChanged. May raise 
Error[notAForm Window, invalidltemKey]. 

ResetChanged: procedure [window: window.Handie, item: ItemKey]; 

ResetChanged sets the changed boolean of item to false. May raise Error[ 
notAFormWindow, invalidltemKey]. 

ResetAllChanged: procedure [window: window.Handie]; 
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ResetAllChanged sets the changed boolean of all items to false. May raise Error[ 
not AFor m Wi ndow] . 

SetChanged: procedure [ 
window: window.Handle, 
item: ItemKey]; 

SetChanged sets the changed boolean of item to true. May raise Error[ notAFormWindow, 
invalidltemKey]. 

SetAllChanged: procedure [ 
window: window.Handie]; 

SetAllChanged sets the changed boolean of all items to true. May raise Error[ 
notAFormWindow]. 



25.2.5 Visibility 

Visibility: type = {visiblejnvisible, InvisibleGhost}; 



An item either is or is not displayed in the form window. If an item is displayed in the form 
window, it is visible. If an item is not currently displayed, it is either invisible or 
invisibleGhost. If it is invisible, it does not take up any space on the screen; any items 
below it move up to take its screen space. If an item is invisibleGhost, the space that it 
would occupy were it visible is white on the screen. An item's visibility can be changed 
anytime by calling SetVisibility. 

GetVisibility: procedure t 
window: window.Handle, 
item: ItemKey] 
RETURNS [visibility: Visibility]; 

GetVisibiiity returns the current visibility of item. May raise Error[notAFormWindow„ 
invalidltemKey]. 



SetVisibility: procedure [ 
window: window.Handle^ 
item: ItemKey, 
visibility: Visibility, 
repaint: boolean «-true]; 



SetVisibility sets the visibility of item. If repaint = true and the item's visibility is 
changing, the form window will be repainted. If repaint = false, the form window will not 
be repainted until Formwindow. Repaint is called. This allows the client to change the 
visibility of several items at once without the screen flashing for each item. Warning: 
After calling SetVisibility with repaint = false. Form window. Re paint must be called. 
Otherwise, the screen will be inconsistent with internal values. May raise 
Error[notAFormWindow, invalidltemKey]. 
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25.2.6 Layout 

The exact layout of items in a form window is done by calling various procedures specified 
below, after creating the items to be laid out. If an item is not explicitly laid out, it will not 
appear in the form window at all. Note that FoimWindow.DefaultLayout may be used when 
the client is not concerned with the exact placement of items, but wants a functional form 
window. 

There are two different types of layout. The most common is flexible layout, which allows 
text, decimal, integer, and window items to grow and shrink (and all other items are 
moved around accordingly) as the user or client changes their values. Flexible layout is 
done by calling such procedures as AppendLine and Appendltem. The other is fixed 
layout, which allows the client to specify exactly where items will go by calling 
SetltemBox, but does not allow text, decimal, integer, and window items to grow or shrink. 
All items stay where they are laid out unless the client calls SetltemBox again. 

25.2.6,1 Flexible Layout 

A form window with flexible layout consists of horizontal lines with zero or more items on 
each line. Lines now are always just tall enough to hold the items on that line. The 
spaceAboveLine parameter specifies the amount of white spae to leave above each line. 
Any desired horizontal spacing may be accomplished by using appropriate margins 
between items. Items may be lined up horizontally by using TabStops (see §25.2.6.2 
below). 

Lines are created by calling AppendLine or InsertLine. Items are placed on a line by 
calling Appendltem or Insertltem. The Append routines are used to add items after the 
previously created line or item. The Insert routines are used to add items between 
previously created items or lines. 

AppendLine: procedure [ 
window: window.Handle« 
spaceAboveLine: cardinal <-0] 
RETURNS [line: Line]; 

AppendLine creates a new line and appends it to the bottom of the form window. All items 
must be placed on a line, so AppendLine must be called before any calls to Appendltem. 
The line returned by AppendLine should be passed to Appendltem or Insertltem. window 
is the Form Window the line is being appended to. May raise Error[notAFormWindow]. 

Line: type; 

Line uniquely identifies a line and is returned by AppendLine and InsertLine. A Line must 
be passed to Appendltem and Insertltem. 

Appendltem: procedure [ 
window: window. Handle, 
item: ItemKey, 
line: Line, 

preMargin: CARDINAL 4-0, 
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tabStop: cardinal <- nextTabStop, 
repaint: boolean 4-true]; 

Appendltem appends item to line. 

preMargin is the number of pixels of white space to place before the left edge of this item. 
If tabs have been set, preMargin is added after placing the item at its tab stop. 

tabStop is the ordinal number of the tab stop at which to place this item. If the default is 
taken, the next tab stop on the line after the previous item is used. If no tabs have been 
defined (i.e., SetTabStops has never been called), tabStop is ignored. See §25.2.6.2 for 
more detail on tabs. 

repaint specifies whether the screen should be repainted after the Appendltem is done. 
When called from the client's LayoutProc, repaint is ignored and the items are not painted 
until the LayoutProc returns. When not called from the client's LayoutProc, and repaint = 
TRUE, the form window will be repainted immediately after appending the item. When not 
called from the client's LayoutProc, and repaint = false, the form window will not be 
repainted until Formwindow. Repaint is called. This allows the client to add several items at 
once without the screen flashing for each new item. Warning: After calling Appendltem 
with repaint = false, Formwindow. Repaint must be called. Otherwise, the screen will be 
inconsistent with internal values. 

May raise Error[notAFormWindow, invaliditemKey, noSuchLine]. 

InsertLine: procedure [ 
window: window. Handle, 
before: Line, 

spaceAboveLine: cardinal <-0] 
RETURNS [line: Line]; 

InsertLine inserts a new line before (above) an existing line. The spaceAboveLine 
parameter indicates how much space (in screen dots) to leave between the previous line 
and this line. This allows clients to leave white space at the top of the form before the first 
line and also provides an easy way to put white space in a form. (See AppendLine for 
details of creating a line. )May raise Error[notAFormWindow, noSuchLine]. 

Insertltem: procedure [ 
window: window. Handle, 
item: ItemKey, 
line: Line, 

beforeltem: ItemKey, 
preMargin: cardinal «-0, 
tabStop: cardinal «- nextTabStop, 
repaint: boolean <-true]; 

Insertltem inserts item to the left of beforeltem on line. See Appendltem for details of 
placing an item on a line. May raise Error [notAFormWindow, invalidltemKey, 
noSuchLine, itemNotOnLine]. 

RemoveltemFromLine: procedure [ 
window: Window. Handle, 
item: ItemKey, 
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line: Line, 

repaint: boolean «- true]; 

RemoveltemFromLine will "unlayout" an item that has been previously laid out. This 
allows clients to move an item from one place on the form to another without destroying 
and recreating the item, by calling RemoveltemFromLine followed by a call to 
Appendltem or Insertltem. RemoveltemFromLine will not destroy the item. The item will 
be "in limbo" until it is laid out again using Appendltem or Insertltem. 

LayoutlnfoFromltem: procedure [ 

window: window.Handle, item: IternKey] 
RETURNS [ line: Line, margin: cardinal, 
tabStop: cardinal, box: window. Box]; 

LayoutlnfoFromltem returns various layout characteristics of item. May raise 
ErrorfnotAForm Window, invalidltemKey]. 

LineUpBoxes: procedure [window: window.Handle, 
items: long descriptor for array of ItemKey <~ nil]; 

Calling this procedure will force the boxes of the specified items to line up vertically, as in 
most Viewpoint property sheets. If no items are specified, and a fixed-pitch font is used, 
the first item on every line will line up as shown in Figure 25. 1. 



tagi 



boxed boolean item 



tagOnLine2 



boxed choice item 



boxed text item 



veryLongTagLine4 



boxed boolean item 



Figure 25.1 LineUpBoxes 



The specified items must be the first item on their line. The longest tag is measured; then 
the boxed part of each item appears at the next available tab stop after the longest tag. 
This also works for non-boxed items. 



25.2.6.2 Tabs 

TabType: type = {fixed, vary}; 

TabStops: type = record! 

variant: select type: TabType from 
fixed = > [interval: cardinal]. 
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vary = > [list: long descriptor for array of cardinal] 
endcase]; 

The client may specify tab stops to facilitate lining up items one directly below the other. 
Tabs may be specified two ways: fixed and varying. Fixed tab stops are specified by a 
single cardinal (interval) that indicates a tab stop at each interval pixel, such as if interval 
= 100, there will be tab stops at 10, 20, 30, etc. Varying tab stops are specified by an array 
OF CARDINAL, each element of the array indicating the number of pixels from the left edge of 
the window. Typically, a client will call SetTabStops at the beginning of the LayoutProc, 
then call AppendLine and Appendltem repeatedly, taking the nextTabStop default for 
each item. 



noTabStop: cardinal « cardinal.last-1 ; 



Can be used with Appendltem and Insertltem to indicate that this item should ignore tab 
stops completely. 

defaultTabStops: TabStops a [fixed[interval: 100]]; 

SetTabStops: procedure [window: window.Handle, tabStops: TabStops]; 

SetTabStops sets the tab stops for window. Any items laid out before to this call will now 
be moved to conform to these tab stops. May raise Error[ notAFormWindow]. 

nextTabStop: cardinal a . . . ; 

Used for item layout, it is the default for the tabStop parameter for Appendltem and 
Insertltem. Indicates that the next item should be placed at the next tab stop. 



GetTabStops: procedure [window: window.Handle] 
RETURNS [tabStops: TabStops]; 



GetTabStops returns the current tab stops for window. If no tab stops have been set for 
window, tabStops will be fixed with an interval of 0. May raise Error[ 
notAForm Wi ndow] . 



25.2.6.3 Fixed Layout 



SetltemBox: procedure [ 
window: window.Handle, 
item: ItemKey, 
box: Window. Box]; 



SetltemBox is used to set the exact position of an item for fixed layout. With fixed layout, 
all items stay right where they are laid out unless the client calls SetltemBox again. With 
fixed layout, text, decimal, integer, and window items will not grow or shrink. SetltemBox 
is incompatible with flexible layout (such as. AppendLine, Appendltem, SetTabStops, 
etc). Note: Either all layout must be flexible, or all layout must be fixed. Attempting to 
mix them will raise Error(notAForm Window, invalidltemKey]. 



25-24 



Viewpoint Programmer's Manual 



25 



25.2.7 Save and Restore 

Restore: procedure [window: window. Handie]; 
Save: procedure [window: window. Handle]; 

Restore and Save deal with restoration of a form window to a previous state. Save causes 
the current item values to be saved. Restore causes the previously saved values to be 
copied back into the form. A Restore done before a Save is a no-op. Save done after Save 
(but before a Restore) overwrites the first Save. These procedures support the Defaults 
and Reset functions of property sheets. May raise Error[notAFormWindow]. 



25.2.8 Miscellaneous TYPEs 



Bitmap: type a record[ 
height, width: cardinal, 
bitsPerLlne: cardinal, 
bits: Environment.BitAddress]; 



A Bitmap is the data structure that is passed to Mal<eBooleanltem and MakeChoiceltem 
for items that are to be displayed as bitmaps, height is the height in pixels, of the bitmap, 
width is the width in pixels, of the bitmap, bits is a pointer to the actual bits in the bitmap. 
bitsPerLine is the number of bits in each line of bits. bitsPerLlne is usually greater than or 
equal to width, and is often a multiple of 16. 

ChangeReason: TYPE a {user, client, restore}; 

A ChangeReason is passed to a GlobalChangeProc, BooleanChangeProc, and 
ChoiceChangeProc. It indicates whether the change was caused by the user, or by the 
client calling SetXXXItemValue, or by the client calling Restore. 



25.2.9 Miscellaneous Item Operations 

GetReadOnly: procedure [window: window.Handle, item: ItemKey] 
RETURNS [readonly: boolean]; 

GetReadOnly returns the current value of the readonly boolean for item. May raise 
Error[notAFormWindow, invalidltemKey]. 

GetTag: procedure [ 

window: window.Handle, 
item: ItemKey] 
returns [tag: xstring.Readerl; 

GetTag returns the tag associated with item. May raise Error[notAForm Window, 
invalidltemKey]. 

SetSelection: procedure [ 
window: window.Handle, 
item: ItemKey, 
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firstChar: cardinal <-0, 

lastChar: cardinal <- cardinal.last]; 

SetSelection sets the current selection to be item. This is useful for helping the user 
correct an incorrect user entry, item must be a text, decimal, or integer item. firstChar is 
the first character of the portion of the string to be selected and highlighted. lastChar is the 
last character of the portion of the string to be selected and highlighted. The defaults for 
firstChar and lastChar causes the entire string to be selected. May raise 
Error[notAFormWindow, invalidltemKey, wrongltemTypel. 

SetlnputFocus: procedure [ 
window: window. Handle, 
item: ItemKey, 

beforeChar: cardinal «- cardinal.last] ; 

SetlnputFocus sets the current input focus to be in item. This is useful for highlighting an 
incorrect user entry, item must be a text, decimal, or integer item. beforeChar is the 
character before which the input focus should go. The default causes the input focus to be 
at the end of the string. May raise ErrorfnotAFormWindow, invalidltemKey,, 
wrongltemType]. 

SetReadOnly: procedure [ 
window: window. Handle, 
item: ItemKey, 
readonly: boolean] 
RETURNS [old: boolean]; 

SetReadOnly sets the current "readOnly-ness" of item and returns the old value. May 
raise Error[notAForm Window, invalidltemKey]. 

SetltemWidth: procedure [window: window. Handle, item: ItemKey, 
width: cardinal]; 

This procedure sets the width of an item. Normally, items are as wide as they need to be to 
display the text of the item (except text, decimal, and integer items whose width is 
specified when the items are created). SetltemWidth overrides the normal width of the 
item and thus could result in the text of the item being truncated. SetltemWidth should 
therefore be used with great caution. In particular, programmers should keep in mind that 
applications are intended to be multinational and strings in other languages are often 
longer than their English equivalents. This layout procedure can only be used with a 
flexible layout. 



25.2.10 NEXT Key 

When the user presses the next key while the input focus is in a form window (more 
exactly: in a text, decimal, or integer item in a form window), the form window does the 
following: 

1. If the item with the input focus has a NextOutOfProc,it is called. This gives the client 
an opportunity to, for example, add another blank text item after this one. 
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2. Find the next text, decimal, integer, or window item. Note: If the client added another 
text item after the one that had the input focus, that new item will be the one found by 
form window. 

3a. If the next item is a text, decimal, or integer item, the input focus and selection are 
moved to that item. 

3b. If the next item is a window item and the window item has a NextlntoProc, it is called, 
giving the window item an opportunity to take the input focus. For example, if the 
window item contains a table of values, the NEXT key could be used to step from entry 
to entry through the table, but the window item's TiP.NotifyProc would have to do this. 
Note: If a NextlntoProc is supplied for a window item, it MUST call TiP.SetlnputFocus 
so that all further NEXT key notifications will go to the window item. When the 
window item no longer wants the NEXT key (such as the user has NEXTed out of the last 
entry of the table), it must call FormWindowoTakeNEXTKey. TakeNEXTKey proceeds as in 
steps 2 and 3. 

3c. If the next item is a window item, but the window item does not have a NextlntoProc, 
the form window repeats steps 2 and 3. 

NextlntoProc: type = procedure [ 
window: wmdow. Handle, 
item: ItemKey]; 

A NextlntoProc can be provided by the client with window items. If provided, the 
NextlntoProc will be called when the user NEXTs into the item using the NEXTkey. (See the 
discussion above.) 

NextOutOfProc: type = procedure [ 
window: window. Handle, 
item: ItemKey]; 

A NextOutOfProc can be provided by the client with text, decimal, and integer items. If 
provided, the NextOutOfProc is called when the user hits the NEXT key while the input 
focus is in an item just before this one. See the discussion above. 

SetNextOutOfProc: procedure [ 
window: window. Handle, 
item: ItemKey, 

nextOutOfProc: NextOutOfProc] 
returns [old: NextOutOfProc]; 

SetNextOutOfProc sets the NextOutOfProc for a text, decimal, or integer item. This is 
useful when the NextOutOfProc for a text item creates another text item after itself. After 
creating the new item, the client will probably want to set the NextOutOfProc for the old 
item to NIL, so that next time the user NEXTs out of the old item, the selection and input 
focus will simply move to the new item rather than creating yet another new item. 
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GetNextOutOfProc: procedure [ 
window: window.Handle, 
item: ItemKey] 
RETURNS [NextOutOfProc]; 

GetNextOutOfProc returns the NextOutOfProc for item. 

TakeNEXTKey: procedure [ 
window: window.Handle, 
item: ItemKey]; 

TakeNEXTKey informs form window that the window item which was handling the next 
item is done with it and the input focus should be passed on to the next item that can take 
it. item identifies the window item that is involved. May raise Error[notAForm Window,, 
wrongltemType]. 



25.2.11 SIGNALS and ERRORS 



Error: error [code: ErrorCode]; 



ErrorCode: type = machine dependent {notAFormWindow(O), wrongltemType, 
invalidChoiceNumber, noSuchLine, alreadyAFormWindow, 
invalidltemKey, itemNotOnLine, duplicateltemKey, 
incompatibleLayout. alreadyLaidOut, last(15)}; 



notAFormWindow 

wrongltemType 

invalidChoiceNumber 

noSuchLine 
alreadyAFormWindow 

invalidltemKey 
itemNotOnLine 

duplicateltemKey 



The term notAFormWindow means the window passed in to 
the procedure is not a form window. Any FormWindow 
procedure, except Create and Isit, may raise this error 

The term wrongltemType means the item passed in to the 
FormWindow procedure is the wrong type. For example, 
GetChoiceltemVaiue must be passed a choice item. 

The term invalidChoiceNumber means the choice number 
supplied does not match any of the choice numbers in the 
Choiceltems. 

The term noSuchLine means the line supplied to 
Appendltem or Insertltem was not previously created. 

The term alreadyAFormWindow means the window passed 
in is already a form window. Raised if a FormWindow is 
passed into Create. 

The term invalidltemKey means an ItemKey was used for 
which there was no item created. 

The term itemNotOnLine means an attempt was made to 
insert an item on a line before an item that is not on that 
line. See Insertltem. 

The term duplicateltemKey means an item was created with 
the key of another item. ItemKeys must be unique. 
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incompatibieLayout The term incompatibleLayout means the client is 

attempting to intermix fixed and flexible layout styles. 

al ready LaidOut The term alreadyLaidOut means an attempt was made to 

specify the layout for an item more than once. 

LayoutError: signal [code: LayoutErrorCode]; 

LayoutErrorCode: type = {onTopOfAnotherltem, notEnufTabsDefined}; 



25.2.12 Multinationalitems 

Flushness: type » simpieTextoispiay.Flushness; 

StreakSuccession: type = simpieTextDispiay.StreakSuccession; 

GetFlushness: procedure [ 
window: window. Handle, 
item: ItemKeyl 
RETURNS [old: Flushness]; 

SetFlushness: procedure [ 
window: window. Handle, 
item: ItemKey, 
new:Flushness] 
RETURNS [old:Flushness]; 

GetStreakSuccession: procedure [ 
window: window.Handle, 
item: ItemKey] 

RETURNS [old: StreakSuccession); 

SetStreakSuccession: procedure [ 
window: window.Handle, 
item: ItemKey, 
new:StreakSuccession] 
RETURNS [old:StreakSuccession]; 



25.3 Usage/Examples 

25.3.1 Calling ChangeProcs 

There are three ways for a client to determine if an item has been changed. (1) The client 
may supply a GlobalChangeProc that governs the entire window, (2) it may supply a 
XXXChangeProc for certain items (such as choice and boolean), and (3) it may examine the 
"changed" boolean associated with each item. 

An item can change because the user changes the item, or because a client calls 
SetXXXItemValue, or because a client calls RestoreAllltems. 
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The two kinds of change procs are called whenever the "changed" boolean goes from false 
to true (whether that is caused by user actions or client actions). The following describes 
the exact order of events for each source of change: 

• User action 

1. Change value of item and set "changed" boolean. 

2. Call local change proc, if any. 

3. Call global change proc, if any. 

• Client call to SetXXXItem Value 

1. Change value of item and set "changed" boolean. 

2. Call local change proc, if any. 

3. Call global change proc, if any. 

• Client call to RestoreAl litems 

1. Change value of item and set "changed" boolean. 

2. Call global change proc, if any, with nullltemKey. 

Note: If a change proc does a SetXXXItemValue, the client should take extreme care to 
prevent infinite recursion. 

25.3.2 Creating a Simple Form Window 

Myltems: TYPE a {boolean, choice, text}; 



shell: starWindowSheii.Create [...]; 

formWindow: starWindowSheii.CreateBody [shell]; 

Formwindow. Create [window: formWindow, makeltems: Makeltems, 

layoutProc: DoLayoutI; 



Makeltems: FormWindow. MakeltemsProc = { 

<< [window: Window.Handle, dientData: LONG POINTER] > > 
tag: xstring.ReaderBody; 

— Make a boolean item 

BEGIN 

booleanLabel: FormWmdow.BooleanltemLabel <— [string[ 

xstring.FromSTRING ["This is a boolean item"]]]; 
tag «- xstring.FromSTRING ["Tag"]; 
FormWindow. MakeBooleanitem [ 
window: window, myKey: Myltems. boolean. ORO, 
tag: @tag, label: booleanLabel, 
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initBoolean: false]; 
end; 

— Make a choice item 

BEGIN 

choicel: xstring.ReaderBody <-xstnng.FromSTRING["Choice One"]; 
choiceZ: xstring.ReaderBody <-xstring.FromSTRING["Choice 2"]; 
choices: array [0..2) of Formwindow.Choiceltem <- [ 

[ string[0, choicel] ], 

[ string[1, choice2] ] ]; 
tag ♦-xstring.FromSTRING ['"Choice item"]; 
Formwindow.MakeChoiceltem [ 

window: window, myKey: Myltems. choice. ord, 

tag: ©tag, values: DESCRiPTOR(choices], 

initChoice: 0]; 
end; 

" Make a text item 

tag <-xstring.FromSTRING ["Text item"]; 
Form Window. MakeTextltem[ 
window: window, myKey: Myltems.text.ORD, 
tag: @tag, width: 30]; 

}; 

OoLayout: Form window. LayoutProc = { 

< < [window: window.Handle, clientData: LONG POINTER] > > 

FormWindow.SetTabStops [window: window, tabStops: [ fixed [100] ] ]; 

line: FormWindow.Line «— Formwindow.AppendLine [window]; 

— Put boolean and choice item on line 1 

FormWindow.Appendltem[window, Myltems.boolean.ORO, line]; 
FormWindow.Appendltem[window, Myltems. choice. ORO, line]; 

" Put text item on line 2 

line <— Form window.AppendLine [window]; 

FormWindow.Appendltem(window, Myltems.text.ORD, line]; 

}; 



23.3.3 Specifying Bitmaps in Choice Items 

This example creates a choice item with three possible values. Two of them are bitmaps, 
one is a string. The initial value to be highlighted is #2, the string. 

"The bits. (These are in a global frame or a file. They MUST be around for the duration of 
the FormWindow since the bits are NOT copied.) 

bm1: FormWindow.Bitmap<- [height: 48, width: 64, bitsPerLine: 64, bits: [mybits1,0, 0]]; 
bm2:FormWindow.Bitmap <- [height: 48, width: 64, bitsPerLine: 64, bits: [mybits2, 0, 0]]; 
mybitsi : long pointer to unspecified @bitmap1 [0]; 
bitmapl : array [0..192) of word [--some bits-]; 
mybits2: long pointer to unspecified <~ @bitmap2[0]; 
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bitmap2: array [0..192) of word [--some bits--]; 

choiceOther: xstring.ReaderBody xstring.FromSTRING("OTHER"]; 

choices: array [0..3) OFFormWindow.Choiceltem «- [ 

[bitmap[0, bm1] ], 

[bitmap(1, bm2] ], 

[string[2, choiceOther] ] 

1; 

FormWindow.MakeChoiceltem[ 
window: window, 
tag: @tag, 

myKey: Myltems. choice. ord, 
values: DESCRiPTORfchoices], 
changeProc: ChoiceChangeProc, 
initChoice: 2]; 



25.3.4 The NEXT Key and Text Items 

This example creates a text item that inserts a new item after itself every time the user 
presses the NEXT key. 

—Make the text item 

Makeltems: Formwindow.MakeltemsProc s 

BEGIN 




FormWindow.MakeTextitem[ 
window: window, 
myKey: Myltems.text.ORD, 
width: 50, 
tag: @tag, 

initString: @initStringLong, 
nextOutOfProc: TextNextOut]; 



end; 

TextNextOut: FormWindow. NextOutOfProc = 

BEGIN 

tag: xstring.ReaderBody <-xstring.FromSTRING["lnserted Item:"]; 

initString: xstring.ReaderBody <- xstring.FromSTRING["l DARE you! Edit ME!"]; 

"Create a new line on whiicli to display t/ie new item 
nextLine: FormWindow.Line <— FormWindow.LayoutlnfoFromltem 

[window, Myltems.testChoice2.ORD]. line; 
line: FormWindow.Line <— FormWindow.lnsertLine[window, nextLine, 60]; 

—create the new item. 
Form Window. Ma keTextltem [ 

window: window, 

myKey: cntr. 
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"Cntr is a counter to keep track of the next available 
— key number since all ItemKeys are unique 

width: 50, 

tag: @tag, 

initString: @initString , 
nextOutOfProc: TextlMextOut]; 



—put the new item on the line 
FormWmdow.Appendltem[ 

window: window, 

item: cntr, 

line: line]; 
cntr <— cntr + 1 ; 

-set the last item's NextOutOfProc to NIL 

[] <-Formwindow.SetNextOutOfProc[window, item, NIL]; 

end; 

25.3.5 Window Items (Including Interaction with the NEXT Key) 

This example creates a window item that wishes to be given control when a user NEXTs 
into it. 



—create the item 

Makeltems: FormWindow.MakeltemsProc s 

BEGIN 

dims: window.Dims «- [200,200]; 

myWindow ^ FormWindow.Mal<eWindowltem[ 
window: window, 
myKey: Myltems. window. ord, 
tag: @tag, 
size: dims, 
destroyProc: nil, 
nextlntoProc: MyNextlnto]; 



-set the display and notify procs 

[] window.SetDisplayProc[myWindow, WindowltemDisplayProc]; 
[] ^TiP.SetlableAndNotifyProc [window: myWindow, 
table: TiPStar.NormalTable[], notify: MyNotify]; 

end; 

—MyNextlnto is called when a user presses the NEXT key "into" the window item 
MyNextlnto: Form window. NextlntoProc = 

BEGIN 

—set the input focus so the window item gets all of the notifications 

TiP.SetlnputFocus [w: myWindow, takeslnput: true]; 

end; 
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"FormWindow is notified so tlie window item no longer requires the next key so 
FormWindow can pass it along to the appropriate item 

MyNotify: TiP.NotifyProc = 

BEGIN 

FOR input: TiP.Results*— results, input.next UNTIL input = nil do 

WITHZ: input SELECT FROM 
atom s > SELECT Z.a FROM 

nextDown » > 

Formwindow.TakeNEXTKey 

[window: myWindow.GetParent, item: Myitems. window. oro]; 

enocase; 
endcase; 
endloop; 
end; 



25.3.6 Hints 

This example creates a text item that has a popup menu associated with it: 
Makeltems: FormWindow. MakeitemsProc s 

BEGIN 

FormWindow.MakeTextltem[ 
window: window, 
myKey: Myltems.text.ORD, 
width: 50, 
tag: @tag, 

initString: @initString, 
hintsProc: TextHints]; 

end; 

— Every time TextHints is called, specify the strings to put into the popup menu. The 
hintAction specifies that when a string is selected from the hints menu, it should replace 
the string in the text item 

TextHints: Formwindow.TextHintsProc = 

BEGIN 

hintsArray < some computation--; 

RETURN [hints: DESCRiPTOR[hintsArray], freeHints: FreeHints, hintAction: replace]; 
end; 

FreeHints: Formwindow.FreeTextHintsProc = 

BEGIN 

—free the strings and whatever other storage here 
end; 
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25.3.7 Saving and Restoring Items 

The following example saves the original values of the items in a form window and 
restores them when the user presses RESET. 

—When creating the FormWindow also call 
Form Window. Save[window]; 

—user changes some values 

—user decides he wants the original values back; presses Reset 
FormWindow. Restore[window]; 
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25.4Index of Interface Items 



Item 


Page 


Item 


Page 


Appendltem: procedure 


21 


Insertltem: procedure 


22 


AppendLine: procedure 


21 


InsertLine: procedure 


22 


Bitmap: type 


25 


Isit: procedure 


5 


BooieanChangeProc: type 


8 


item:ltemKey 


5 


BooleanltemLabel: type 


8 


ItemKey: type 


7 


BooleanitemLabelType: type 


8 


ItemType : type 


7 


ChangeReason: type 


25 


LayoutError: signal 


29 


ChoiceChangeProc: type 


10 


LayoutErrorCode; type 


29 


ChoiceHintsProc: type 


11 


LayoutlnfoFromltem: procedure 


23 


Choicelndex: type 


10 


LayoutProc: type 


5 


Choiceltem: type 


10 


Line: type 


21 


Choiceltems: type 


10 


LineUpBoxes:pROCEDURE 


23 


ChoiceltemType: type 


10 


LookAtTextltemValue: procedure 


17 


CommandProc: type 


12 


MakeBooleanltem: procedure 


7 


Create: procedure 


4 


MakeChoiceltem: procedure 


8 


DefaultLayout: LayoutProc 


4 


MakeCommandltem: procedure 


12 


defaultTabStops:TabStops 


24 


MakeOecimalltem: procedure 


13 


Destroy: procedure 


4 


Makelntegerltem: procedure 


14 


Destroyltem: procedure 


16 


MakeltemsProc: type 


6 


Destroyltems: procedure 


16 


MakeMuitipleChoiceltem: procedure 


11 


DoneLookingAtTextitemValue: procedure 


18 


MakeTagOnlyltem: procedure 


12 


Error: error 


28 


MakeTextltem: procedure 


13 


ErrorCode: type 


28 


MakeWindowltem: procedure 


15 


Flushness: type 


29 


MinDimsChangeProc:TYPE 


4 


FreeChoiceHintsProc: type 


11 


MultipleChoiceChangeProc: type 


12 


FreeTextHintsProc: type 


15 


NeededDims: procedure 


6 


GetBooleanltemValue: procedure 


17 


NextlntoProc: type 


27 


GetChoiceltemVaiue: procedure 


17 


NextOutOfProc: type 


27 


GetClientData: procedure 


4 


nextTabStop: cardinal 


24 


GetDecimailtemValue: procedure 


17 


noTabStop:cARDiNAL 


24 


GetFlushness: procedure 


29 


nullltemKey: ItemKey 


7 


GetGlobalChangeProc: procedure 


5 


NumberOf Items: procedure 


6 


GetlntegerltemVaiue: procedure 


17 


OutlineOrHlghlight:TYPE 


10 


GetMultipleChoiceltemValue: procedure 


17 


Repaint: procedure 


6 


GetNextAvailableKey:PROCEDURE 


18 


RemoveltemFromLine:pROCEDURE 


22 


GetNextOutOfProc: procedure 


28 


ResetAllChanged: procedure 


19 


GetReadOnly: procedure 


25 


ResetChanged: procedure 


19 


GetStreakSuccession: procedure 


29 


Restore; procedure 


25 


GetTabStops: procedure 


24 


Save: procedure 


25 


GetTag: procedure 


25 


SetAllChanged: procedure 


20 


GetTextltemValue: procedure 


17 


SetBooleanltemValue: procedure 


18 


GetVisibility: procedure 


20 


SetChanged: procedure 


20 


GetWindowltemVaiue: procedure 


17 


SetChoiceltemValue: procedure 


18 


GetZone: procedure 


5 


SetDecimalltemValue: procedure 


18 


GlobalChangeProc: type 


4 


SetFlushness: procedure 


29 


HasAnyBeenChanged: procedure 


19 


SetGlobalChangeProcs:PROCEDURE 


5 


HasBeenChanged: procedure 


19 


SetlnputFocus: procedure 


26 
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Item Page 

SetlntegerltemValue: procedure 18 

SetltemBox: procedure 24 

SetltemWidth: PROCEDURE 26 
SetMuitipieChoiceltemValue: procedure 19 

SetNextOutOfProc: procedure 27 

SetReadOnly: procedure 26 

SetSelection: PROCEDURE 25 

SetStreakSuccession: procedure 29 

SetTabStops: procedure 24 

SetTextltemValue: procedure 19 

SetVisibility: procedure 20 

SetWindowltemSize: PROCEDURE^ 16 

StreakSuccession: type 29 

TabStops: type 23 

TabType: type 23 

TakeNEXTKey: procedure 28 

TextHlntAction: TYPE 14 

TextHintsProc: TYPE 14 

Visibility: type 20 
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26.1 Overview 



The FormWindowMessageParse interface provides procedures that parse strings to 
produce various FormWindow types. These strings are usually acquired from a message 
file. Currently, only FormWindow.Choiceltems are supported. 

26.2 Interface Items 

ParseChoiceltemMessage: procedure [ 

choiceltemMessage: xstnng. Reader, 

zone: uncounted zone] 
RETURNS [choiceltems:FormWindow,Choiceltems]; 

Parses a choiceltemMessage (presumably retrieved using XMessage.Get) with the 
following syntax: "choiceString:choiceNumber@choiceString:choiceNumber@|", where 
choiceString is the string to be displayed for that choice, choiceNumber is the fixed 
number associated with that choice, @ is the separator between choices, and | indicates 
the point at which to wrap the choices. The choices will be displayed in the order they 
appear in the message, choiceltems is a descriptor for an array that must be freed using 
FreeChoiceltems. 

FreeChoiceltems: procedure [ 

choiceltemsiFormWindow. Choiceltems, 
zone: uncounted zone]; 

Frees the array and everything it points to (strings). 

26.3 Usage/Examples 

The following example is taken from the folder implementation. The message acquired by 
XMessage.Get looks like "Sorted :0@Unsorted: 1 ". 

choices: FormWindow.Choiceltems <— FormWindowMessageParse. ParseChoiceltemMessage [ 
XMessage.Get[mh, FoiderOps.kpsSorted], z]; 
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Formwindow.MakeChoiceltem [ 
window: window, 
myKey: MyltemType. sorted. ORD, 
values: choices, 
initChoice: sorted. ORD, 
changeProc: SortedChanged ]; 

FormWindowMessageParse. FreeChoiceltems[choices, z]; 
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26.4 Index of Interface Items 

Item Page 

FreeChoiceltems: procedure 1 

ParseChoiceltemMessage: procedure 1 
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27.1 Overview 



The IdleControl interface provides access to ViewPoint's basic controlling module. 

Viewpoint's control loop is organized as a series of two out-calls to a greeter procedure and 
a desktop procedure. Each procedure is implemented as a procedure variable, initialized to 
an appropriate no-op, 

Interface procedures allow the client to plug in its own greeter and desktop procedures. A 
plugged-in procedure will then be called the next time that the control routine goes 
around the loop. 



27.2 Interface Items 



IdleControl keeps track of one GreeterProc and a list of DesktopProcs. A client may plug 
in a number of DesktopProcs and specify the one to be called by the value of the Atom.ATOM 
returned by the GreeterProc. 

27.2.1 DesktopPlug-in 

DesktopProc: type = procedure; 

SetDesktopProc: procedure [atom: Atom. atom, desktop: DesktopProc] returns [old: 
DesktopProc]; 

SetDesktopProc allows the client to specify the desktop procedure to be called in the 
control loop, desktop is the procedure to be called, atom is the Atom.ATOM associated with 
desktop, old is the previously plugged-in desktop procedure. 

GetDesktopProc: procedure [atom: Atom.ATOM] returns [DesktopProc]; 



27.2.2 Greeter Plug-in 

GreeterProc: TYPE = procedure returns [Atom.ATOM]; 
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SetGreeterProc: procedure [new: GreeterProc] returns [old: GreeterProc]; 

SetGreeterProc allows the client to specify the greeter procedure to be called in the control 
loop, new is the procedure to be called, old is the previously plugged-in greeter procedure. 

GetGreeterProc: procedure returns [GreeterProc]; 

DoTheGreeterProc: GreeterProc; 

DoTheGreeterProc calls the currently plugged-in GreeterProc. 



27.2.3 Idle Loop 

The control loop is the logical equivalent of : 
DO 

atom: Atom.ATOM pluggedlnGreeterProc []; 
pluggedlnDesktopProc <- GetDesktopProcWithAtom[atom]; 
piuggedinDesktopProcG; 

ENDLOOP; 
Idle: PROCEDURE 

Idle is called or FORKed to enter the idle state. 
Only clients who start the world should call Idle. 

27.3 Usage/Examples 

In the following example, the GreeterProc (IdleProc) displays a bouncing square on the 
screen. The GreeterProc is set in the mainline code of the module The DesktopProc and 
GreeterProc can be initialized in different modules as long as they agree on the Atom.ATOM 
(in this case StarDesktop). 

star Desktop Atom: Atom.ATOM <- Atom. MakeAtom["StarDesktop"L]; 

IdleProc: idieControi. GreeterProc = begin— display a bouncing square until the user 
presses any key 

RETURN [star Desktop Atom]; 

end; 

StarDesktop: procedure = begin 
—do Star logon 

—initialize and display Star desktop 

—wait until Logoff 

end; 

(nit: PROCEDURE = 
BEGIN 

[] IdleControl. SetG reete rProc(l d I eProc] ; 

[] ^idieControi.SetDesktopProc [starDesktopAtom, StarDesktop]; 
end; -- oflnit 
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27.4 Index of Interface Items 



Item Page 

DesktopProc: type 1 

DoTheGreeterProc:GreeterProc 2 

DoTheGreeterProc: PROCEDURE 2 

GetOesktopProc 1 

GetGreeterProciPROCEDURE 2 

GreeterProc: type 1 

Idle: procedure 2 

SetDesktopProc: procedure 1 

SetGrieeterProc.PROCEDURE 2 
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28,1 Overview 



KeyboardKey is a keyboard registration facility. It provides clients with a means of 
registering "system-wide" keyboards (available all the time, like English, French, 
European), a special keyboard (like Equations), and/or client-specific keyboards (such as 
these available only when the client has the input focus). The labels from these registered 
keyboards are displayed in the softkeys when the user holds down the KEYBOARD key. 



The client adds system keyboards by calling AddToSystem Keyboards. The client registers 
a special keyboard by calling RegisterClientKeyboards with the SPECIALKeyboard 
parameter. The client registers client-specific keyboards by calling 
Regis terClientKey boards with the keyboards parameter. 



28.2 Interface Items 



28.2.1 System Keyboards 



A system keyboard is defined as one that is available to all clients who wish to recognize 
some general set of keyboards. (The default case is for a client to recognize system 
keyboards.) Examples of system keyboards are the various language keyboards--English, 
French, European, etc., and the general-purpose keyboards - Math, Office, Logic, and 
Dvorak. 



AddToSystemKey boards: procedure [keyboard; BiackKeys.Keyboardj; 

The AddToSystemKeyboards procedure registers a client's keyboard interpretation with 
the keyboard key manager. The client is expected to provide a pointer to a keyboard 
record. This keyboard will be made available whenever system keyboards are available. 



May raise ErrorialreadylnSystemKeyboardsj. 

RemoveFromSystem Keyboards: procedure [keyboard: BiackKeys.Keyboard]; 
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Removes a Keyboard from the list of system keyboards. jUiik 

i 

May raise ErrortnotlnSystemKeyboards). 

28.2.2 Client Keyboards 

A client keyboard is defined as one that is specific to the application and would have no 
meaning in a different context. Examples are the special keyboards (such as equations and 
fields) and Spreadsheet and 3270 keyboards. 

A client registers its keyboards with the keyboard manager when it gets control (gets the 
inputFocus). RegisterClientKeyboards tells the keyboard manager what keyboards should 
be made available to the user when the KEYBOARD key is held down. When the client loses 
control (releases the input Focus) it should call RemoveClientKeyboards to release its 
keyboards. Only 0-1 set of client keyboards is registered at any given time. If no client is 
registered, then all system keyboards are available to the user. 

RegisterClientKeyboards: procedure [ 
wantSystemKeyboards: boolean -(-true. 
SPECIALKeyboard: BiackKeys.Keyboard <-nil. 

keyboards: long descriptor for array of siackKeys.KeyboardObject <- nil); 

RegisterClientKeyboards establishes a list of client keyboards with the keyboard 
manager. This should occur at the same time the client takes the input focus. 
wantSystemKeyboards specifies whether the client wishes to recognize system keyboards. ^Hfll, 
SPECIALKeyboard denotes the keyboard to be invoked by pressing the key combination of | 
KEYBOARD key and the softkey labeled "Special". The keyboards array contains any other 
client keyboards. A typical case is for a client to provide only a Special keyboard and 
wantSystemKeyboards = true. If wantSystemKeyboards = false the client should set one 
of his keyboards using SetKeyboard (see section 2.3) 

RemoveClientKeyboards: procedure ; 

RemoveClientKeyboards removes the clients keyboards from the keyboard managers list. 
This list of available keyboards will revert to system keyboards only. The "Set" keyboard 
will be the last system keyboard that was "Set" (either by the user or a call to 
SetKeyboard). It is the client's responsibility to make sure his keyboards are removed 
when relinquishing control. It would be appropriate for this to be done as part of a 
TiP.LoslngFocusProc. 



28.2.3 Setting and Enumerating Keyboards 

Note: Most clients will probably not have reason to use the information in this section. 
SetKeyboard: procedure (keyboard: siackKeys.Keyboardj; 

SetKeyboard sets the current keyboard to keyboard. This keyboard will remain the 
current keyboard until the user presses a KEYBOARD key/SoftKeyOption/Set combination, 
which chooses a new keyboard, or until another SetKeyboard command is encountered. 

SetKeyboard is provided for those clients who have reason to set a keyboard 
programmatically. The usual case is for the user to cause a keyboard to be set by pressing 
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the key combination KEYBOARD key/SomeSoftKeyDesignatingAKeyboard. However, for a 
client calling RegisterClientKeyboards with wantSystemKeyboards = false it is 
appropriate to call SetKeyboard[@oneOf CI ientKey boards] . (Otherwise there would be no 
typing possible until the user made a keyboard choice through the KEYBOARD key/SoftKey 
routine.) The other primary reason for calling SetKeyboard would be to set an initial 
keyboard at boot time. 

EnumerateKeyboards: procedure [class: KeyboardClass, enumProc: EnumerateProc]; 
EnumerateProc: TYPE = PROCEDURE(keyboard: BlackKeys. Keyboard, class: KeyboardClass] 

RETURNS[StOp: BOOLEAN <- FALSE]; 

EnumerateKeyboards calls the specified EnumerateProc until the Stop boolean becomes 
TRUE or until there are no more keyboards to enumerate. When calling 
EnumerateKeyboards, the client may specify which keyboards he wants enumerated: 
system, client, special, or all of the registered keyboards. When the keyboard manager 
calls the client's EnumerateProc, the keyboard returned will be qualified by class: client, 
system, or the special keyboard.. 

KeyboardClass: TYPE = {system, client, special, all, none}. 

system = A system keyboard is defined as one that is available to all clients who wish to 
recognize some general set of keyboards. Examples of system keyboards are 
the various language keyboards - English, French, European, etc., and the 
general-purpose keyboards-Math, Office, Logic, and Dvorak. 

client sa A client keyboard is defined as one that is specific to the application. These 
are the keyboards registered in the keyboards array by the client calling 
RegisterClientKeyboards. 

special = A client-specific keyboard is invoked by pressing the combination of 
KEYBOARD key and the softkey labeled "Special". Specifically, this is the 
keyboard registered by the client as SPECIALKeyboard when calling 
RegisterClientKeyboards. 

all = All keyboards: system, client, and special. 

28.2.4 Keyboard Window Plug-in 

This section pertains only to those clients interested in implementing a Keyboard Window 
facility. 

ShowKeyboardProc: type = procedure, 
SetShowKeyboardProc: procedure [ShowKeyboardProc]; 
GetShowKeyboardProc: procedure returns [ShowKeyboardProc]; 

SetShowKeyboardProc and GetShowKeyboardProc provide an interface between a 
keyboard window application and KeyboardKey's "Show" key. The clients 
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ShowKeyboardProc will be called whenever the user presses the key combination 
KEYBOARD key/Show. This gives the client the opportunity to display a keyboard window. 

28.2.5 Errors 

Error: ERROR[code: ErrorCodej; 

ErrorCode: type = {alreadyinSystemKeyboards, notlnSystemKeyboards, 
insufficientSpace}; 

28.3 Usage/Examples 

25.3.1 AddToSystemKey boards Example 

In this application a keyboard has been defined that will be useful across all applications. 
Registering it as a system keyboard will make it available globally. 

usefulKeyboard: BiackKeys.KeyboardObject <r- 
[charTranslator: (proc: MyCharTrans.data: nil], 
pictureProc: MapPicture, 

label «-xstring.FromStrlngi"t/sefu/ Keyboard "LJl; 
KeyboardKey.AddToSystemKeyboards[@myUsefulKeyboardl; 

The keyboard manager will add the keyboard usefulKeyboard to the list of registered 
system keyboards and a key labeled Useful Keyboard to its labels for the KeyboardKey 
soft keys. When the user pushes the soft key labeled Useful Keyboard, MyCharTrans will 
be registered as the TiP.CharTranslator, and if the keyboard window is open, MapPicture 
will be called so that the picture and geometry table can be mapped. 

28.3.2 Special Keyboard Example 

This example contains a keyboard that is specific to a particular application and will be 
available to the user through the "Special" key. The user should also be able to use the 
system keyboards in this application. Notice that it is appropriate to default the label 
when specifying a Special keyboard, because this keyboard will be presented to the user as 
the current Special keyboard and labeled as such. 

AddMyClientKeyboards: procedure = 

BEGIN 

specialKeyboard: BiackKeys.KeyboardObject; 

fileName: xstring.ReaderBody *- xstring.FromSTRING["JSpecial.TIP"L], 
table: TiP.Table «-Tip.CreateTable(@fileName]; 
[] «-TiP.SetNotifyProcForTableCtable. NotifyProcj; 
specialKeyboard <- [table: table); 
KeyboardKey.RegisterClientKeyboardsl 
wantSystemKeyboards:TRUE, 
SPECIALKey board: @specialKeyboard]; 
END; AddMyClientKeyboards 
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LosingFocusProc: TiP.LosingFocusProc = 
<<|w: window.Handle, data: long pointer]>> 

BEGIN 

KeyboardKey.RemoveClientKeyboardsn; 
--release any data structures I don't want to keep around 
END; — LosingFocusProc 

28.3.3 Registering Multiple Client Keyboards Example 

This example deals with a client who has a special keyboard and several client-specific 
keyboards and does not plan to allow the user to use any system keyboards while in this 
application. 

keyboardRecords: array [0..3) of BlackKeys.KeyboardObject; records filled in 

specialKeyboard: BiackKeys.Keyboard; elsewhere 

AddCtientKeyboards: procedure = 

BEGIN 

KeyboardKey.RegisterClientKeyboardsl 
wantSystemKeyboards: false, 
SPECIALKeyboard: specialKeyboard, 
keyboards: DESCRiPTOR(keyboardRecords]]; 
KeyboardKey.SetKeyboard[@keyboardRecords[0]] 
END; AddClientKeyboards 

LosingFocusProc; TIP LosingFocusProc = 
< <(w: Window.Handle, data; long pointer] > > 

BEGIN 

KeyboardKey.RemoveClientKeyboardst]; 
-release any data structures I don't want to keep around 
END; — LosingFocusPro 
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28.4 Index of Interface Items 



Item Page 

AddToSystemKeyboards: PROCEDURE 1 

EnumerateKeyboards: PROCEDURE 3 

EnumerateProc: type 3 

Error: error 4 

ErrorCode: type 4 

GetShowKeyboardProc. procedure 3 

KeyboardClass: type 3 

RegisterClientKeyboards: procedure 2 

Removed ientKeyboards: procedure 2 

RemoveFromSystemKeyboards: procedure 1 

SetKeyboard: procedure 2 

SetShowKeyboardProc: procedure 3 

ShowKeyboardProc; type 3 
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29.1 Overview 

The BlackKeys and KeyboardKey interfaces provide the framework for including a 
keyboard window in ViewPoint. The window implementation is a plug-in (see 
KeyboardKey.SetShowKeyboardProc). This KeyboardWindow interface and its 
implementation provide one such keyboard window. 

29.2 Interface Items 
29.2.1 Default Values 

defaultPicture: BiackKeys.Picture; 
defaultGeometry: BiackKeys.Geometry Table,- 

The default values provided by this keyboard v^^indow implementation correspond to the 
standard English keyboard. 

DefaultPictureProc: BiackKeys.PictureProc; 

DefaultPictureProc returns defaultPicture and defaultGeometry to the caller when 
actions acquire. Clients may specify pictureProc: KeyboardWindow. DefaultPictureProc in 
their BlackKeys.KeyboardObject if they wish to display the default picture in the keyboard 
window while their keyboard is in effect. 

picture = BlackKeys.nullPicture or BiackKeys.PictureProc = nil will result in the keyboard 
window displaying only gra}'^ in the viewing region. 
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29.2.2 Geometry Table Structure 

Geometry TableEntry: type = record[ 
box: Box, key: Keystations, shift: ShiftState); 

Box: TYPE = RECORDtplace: Window. Place, width; INTEGER, height: INTEGER]; 

Area within the bitmap that will generate a particular keystroke when selected with the 
mouse. 

Keystations: TYPE = machine dependent { 

k1. k2, k3. k4, kS, k6, k7. k8, k9, klO, k11, k12. k13, k14, k15, k16, k17, 
k18, k19. k20, k21, k22, k23. k24, k25, k26. k27. k28, k29, k30, k31, k32. 
k33. k34, k35, k36, k37, k38. k39, k40. k41, k42, k43, k44, k45, k46, k47. 
k48, a1 , ^2, a3, a4, a5, a6, a7, a8, a9, a10, a1 1 , a1 2, last(96) }; 

The following is a translation to LeveliVKeys.KeyName: 



kl = 


= > One; 


k2 = 


= > Q; 


k3 = 


= > A; 


k4 = 


= > Two; 


k5 = 


= > Z; 


k6 = 


= > W; 


k7 = 


= > S; 


k8 = 


= > Three; 


k9 


= > X; 


klO 


= > E; 


kll 


= > D; 


kl2 


= > Four; 


kl3 


= > C; 


kl4 


= > R; 


kl5 


= > F; 


kl6 


= > Five; 


kl7 


= > V; 


kl8 


= >T; 


kl9 


= > G; 


k20 


= > Six; 


k21 


= >B; 


k22 


= > Y; 


k23 


= > H; 


k24 


= > Seven; 


k25 


= > N; 


k26 


= > U; 


k27 


= > J; 


k28 


= > Eight; 


k29 


= > M; 


kSO 


= >l; 


kai 


= > K; 


k32 


= > Nine; 


k33 


= > Comma; 


k34 


= >0; 


k35 


= > L; 
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k36 = > Zero; 
k37 = > Period; 
k38 = > P; 
k39 = > SemiColon; 
k40 = > Minus; 
k41 - > Slasii; 
k42 = > LeftBracket; 
k43 = > CloseQuote; 
k44 = > Equal; 
k45 = > RightBracket; 
k46 = > OpenQuote; 
k47 = > Key47; 
k48 = > Tab; 
al = > ParaTab; 
a2 = > BS; 
a3 = > Lock; 
a4 = > NewPara; 
a5 = > LeftShift; 
a6 = > RightShift; 
a7 = > Space; 
a8 = > AS; 
a9 = > A9; 
alO = > AlO; 
all = > All; 
al2=>A12; 

ShiftState: type = (None. One, Two, Both}; 

Simulates the position of the shift keys associated with the keystroke. 

29.2.3 Bitmap Structure 

BlackKeys.Picture. bitmap is a long pointer. It is further defined within this keyboard 
window implementation as follows: bitmap points to the bits of the keyboard bitmap 
where dims = [505, 145] and bitmapBltWidth = 32*16. 

29.2.4 Getting to the Keyboard Window Handle 

GetDlsplayWindow: procedure returns lwindow,Handle]; 

Returns handle to the body window of the keyboard window. 

29.3 Usage/Examples 

29.3.1 Using DefaultPictureProc 

DefineKeyboard: procedure = 

BEGIN 

nameStrlng: xstring.ReaderBody <-xstring.FromSTRINGrZulu"L] 
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zuluKeyboardRecord: BiackKeys.KeyboardObject ^( 
table: NIL, 

charTranslator: [MakeChar, nil], 

pictureProc: Keyboardwindow.DefaultPictureProc, 

label: xsti-ing.CopyToNewReaderBody(@nameString, Heap.systemZone]], 
—save the pointer to the record somewhere for future use — 
END; "DefineKeyboard -- 



DefineKeyboard: procedure = 

BEGIN 

nameString: xstring.ReaderBody *- xstring.FromSTRING["Swahili"Ll 

swahiliKeyboardRecord: siackKeys.KeyboardObject <-[ 
table: NIL. 

charTranslator: [MakeChar, nil], 
pictureProc: MapBitmapFlle. 

label: xstring.CopyToNewReaderBody(@nameString, Heap.systemZone]],- 
— save the pointer to the record somewhere for future use — 
END; "DefineKeyboard -- 

MapBitmapFile: siackKeys.PictureProc = 

BEGIN 

pixPtr: BlackKeys.Picture.bitmap«-BlackKeys.nullPicture; 

SELECT actlon FROM 

acquire => 

{—Do the right thing to map the bitmap. Uses the default Geometry table --. 
RETURN[pixPtr, Keyboardwindow.defaultGeometry] }; 
release = > [—Do the right thing to unmap the bitmap 
RETURN[BiackKeys.nullPicture, NIL] } 
END; -- MapBitmapFile 



box: [place: [x: XXX, y: XXX]. w idth: XXX, height: XXX], key: XXX, shift: XXX 



29.3.2 Using defaultGeometry 



29.3.3 Sample Geometry Table Entries 



[[19, 111,27, 27],k48, None 
[[51, 111,27, 141, kl. One 
[[51,241,27, 14], kl. None 
[[83,111,27, 14], k4, One 
[[83, 24], 27, 14], k4, None 



" 'tab' key, dims: whole key picture 

— shifted '1' key, dims: upper half key 

— '1' key, dims: lower half key 

— shifted '2' key, dims: upper half key 

— '2' key, dims: lower half key 
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29.4 Index of Interface Items 



Item Page 

bitmap structure 3 

Box: TYPE 2 

defaultGeometry: BiackKeys.Geometry Table 1 

defauitPlcture: BiackKeys.Plcture 1 

DefaultPictureProc: BiackKeys.PlctureProc 1 

Geometry TableEntry: type 2 

GetOisplayWIndow: PROCEDURE 3 

Keystations: type 2 

ShiftState: type 3 



29 Keyboard Window 
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30.1 Overview 

LevelJVKeys is documented in the Pilot Programmer's Manual: 610E00160; however, the 
names of several keys were changed for ViewPoint. The key names now more closely 
match the names on the physical keys. 

30.2 Interface Items 

OPEN ks: KeyboardWindow.KeyStations; 
DownUp: TYPE = ks.DownUp; 

Bit: TYPE = ks.Bit; 

KeyBits: type = packed array KeyName of OownUp; 

KeyNamerTYPE = machine dependent { 
notAKey(O), 

KeysetKks.KSI), Keyset2(ks.KS2). Keyset3(ks.KS3). Keyset4(ks.KS4), 
Keyset5(ks.KS5), 

MouseLeft(ks.MI), MouseRight(ks.M3), MouseMidclle{ks.M2), 
Five(ks.k16), Four(ks.k12). Six(ks.k20), E{ks.k10), Seven(ks.k24), 
D(ks.k1 1 ), U(ks.k26), V(ks.k1 7), Zero(ks.k36), K(ks.k31 ), Minus(ks.k40), 
P(ks.k38), Slash(ks.k41 ), Font(ks.R8), Same(ks.L8), BS(ks.A2), 
Three(ks.k8), Two(ks.k4), W(ks.k6), Q(ks.k2). S(ks.k7), A(ks.k3), 
Nine(ks.k32), l(ks.k30K X(ks.k9), 0(ks.k34), L(ks.k35), Comma(ks.k33), 
CloseQuote(ks.k43), RightBracket(ks.k45), Open(ks.LII), Keyboard(ks.RII), 
One(ks.kl), Tab(ks.k48), ParaTab(ks.AI), F(ks.k15), Props(ks.L12), 
C(ks.k13)J(ks.k27), B(ks.k21K Z(ks.k5), LeftShift(ks.A5), 
Period(ks.k37), SemiColon(ks.k39), NewPara(ks.A4), 
OpenQuote(ks.k46), Delete(ks.L3), Next(ks.RI), R(ks.k14), T(ks.k18), 
G(ks.k19). Y(ks.k22), H(ks.k23), Eight(ks.k28K N(ks.k25), M(ks.k29), 
Lock(ks.A3), Space(ks.A7), LeftBracket(ks.k42). Equal(ks.k44), 
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RightShift(ks.A6), Stop(ks.R12), Move(ks.L9), Undo(ks.R6), Margins(ks.R5), 
R9(ks.R9), LIO(ks.LIO), L7(ks.L7), L4(ks.L4), LI(ks.LI), A9(ks.A9), 
R10(ks.R10). A8(ks.A8), Copy(ks.L6), Find(ks.L5), Again(ks.L2), 
Heip(ks.R2), Expand(ks.R7), R4(ks.R4), 02(ks.D2), D1(ks.D1), 
Center(ks.T2), TI(ks.TI), Bold(ks.T3). ltallcs(ks.T4), Underline(ks.T5), 
Superscript(ks.T6), Subscript(ksT7), Smaller(ks.T8). TIO(ks.TIO), 
R3(ks.R3). Key47(ks.k47), A10(ks.A10), Defaults(ks.T9), A1 1(ks.A11), 
A12(ks.A12)}; 
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30.3 Index of Interface Items 
Item 



F*age 



DownUp: Type 
Bit: Type 
Key Bits: Type: 
KeyName: Type 

OPEN l<s:KeyboardWindow.KeyStations 
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MenuData 



31.1 Overview 

The MenuData interface defines the data abstraction that is a titled list of named 
commands. It defines the object formats for a menu item and a menu as well as how to 
create and manipulate these objects. It is not concerned with how a menu might be 
displayed to a user. 

31.2 Interface Items 

31.2.1 Menu and Item Creation 



Items and menus are the two primary data objects in the MenuData interface. Items are a 
name-procedure pair that constitute a command. Menus are an abstraction representing a 
collection of items to be presented to the user. These objects can be built and deallocated 
through this interface. 

Createltem: PROCEDURE [ 

zone: UNCOUNTED ZONE, 

name:xstring.Reader, 

proc: MenuProc, 

itemData: long unspecified 0] 

RETURNS [ItemHandie]; 

ItemHandie: TYPE s long pointer to Item; 

Item: type = Privateltem; 

MenuProc: type = procedure [ 

window: window. Handle, menu: MenuHandle, itemData: long unspecified]; 

Createltem builds an item record in the indicated zone to be added to a menu. The name 
parameter is copied so it can be in the client's local frame. The proc parameter is the 
command procedure that will be associated with a command name in an item. Client data 
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that must be available when the MenuProc is called can be passed via the itemData 
parameter. 



An Item is the representation for a {command-name, command-procedure} pair. The 
"nameWidth" field, if non-zero, is the display width of the name. It may be set by a module 
that computes the width using SetltemNameWidth(see §31.2.3). Except for that, an item 
is read-only. 

Destroyltem: procedure [zone: uncounted zone, item: ItemHandle]; 

This procedure destroys the item, recovering the space, zone must be the zone in which the 
item was created, and item is the ItemHandle returned by Createltem. The item should 
not be in use when this procedure is called. 

CreateMenu: procedure [ 
zone: uncounted zone, 
title: ItemHandle, 
array: ArrayHandle, 

copyltemslntoMenusZone: boolean false ] 
RETURNS [MenuHandle]; 

ArrayHandle: TYPE = long descriptor for array of ItemHandle; 

MenuHandle: TYPE = long pointer to MenuObject; 

MenuObject: type = PrivateMenu; | 

CreateMenu builds a menu record in zone, title is an item containing the menu's title and 
array contains the collection of items that make up the menu. The items pointed to by the 
array and the title parameters will only be copied if copyltemslntoMenusZone is true. 
Since item records are "read-only," an item can be in several menus without copying. The 
procedure associated with the title item is currently unused and should be nil for future 
compatibility. 

DestroyMenu: procedure [zone: uncounted zone, menu: MenuHandle ] 

DestroyMenu destroys the menu, recovering the space, zone must be the zone in which 
the menu was created; menu is the MenuHandle returned by CreateMenu. It should only 
be called when the menu is not in use. There is no explicit way to test if a menu is in use. 

Items are not typically destroyed, but their space may be recovered by calling zone. free 
[ItemHandle]. The zone below is exported for clients that do not wish to manage their own. 

PublicZone: procedure returns [uncounted zone]; 



31.2.2 Menu Manipulation 



Addltem: procedure [menu: MenuHandle, new: ItemHandle] » 
INLINE {menu.swapltemProc [menu: menu, old: nil, new: new]}; 
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Subtractltem: procedure [ 

menu: MenuHandle, old: ItemHandie] s 

INLINE {menu.swapltemProc [menu: menu, old: old, new: nil]}; 

Swapltem: procedure [ 

menu: MenuHandle, new, old: ItemHandie ] = 

INLINE {menu.swapltemProc [menu: menu, old: old, new: new]}; 

Tliese procedures alter a menu in the obvious ways. Tliey call through the swapltemProc 
field in the menu object. This allows a module that posts a menu to "plant" a procedure in 
the swapltemProc field and thus get control on add/subtract/swap requests. With control, 
data can be monitored appropriately. 

SetSwapltemProc: procedure [menu: MenuHandle, new: SwapltemProc] 
RETURNS [old: SwapltemProc]; 

SwapltemProc: TYPE - procedure [ 

menu: MenuHandle, old, new: ItemHandie]; 

The SwapltemProc is the work horse for manipulating menus, as evidenced by the inline 
calls above. It can be changed by calling SetSwapltemProc. 

UnpostedSwapitemProc: SwapltemProc; 

This procedure is the standard procedure that is placed in a menu's swapltemProc when 
the menu is created. It is in the MenuData implementation, and it can handle altering a 
menu when it is not posted. As discussed above, if a routine that posts a menu wants to get 
control on attempted menu alterations, it should alter the swapltemProc in the menu. 
When it has finished posting the menu, it should store MenuData. UnpostedSwapitemProc 
as the swapltemProc. Alternatively, it can call MenuData. UnpostedSwapitemProc from 
within its own swapltemProc to perform the actual alteration of the menu object. 



31.2.3 Accessing Data 



The following provide procedural access to the internal data structures for an item or 
menu. 



ItemData: procedure [item: ItemHandie] returns [long unspecified]; 

ItemName: procedure [item: ItemHandie] 
returns (name: xstrmg.ReaderBody]; 

SetltemNameWidth: procedure [item: ItemHandie, width: cardinal] = 
inline {item.nameWidth <- width}; 

ItemNameWidth: procedure [item; ItemHandie] returns [cardinal] = 
inline {return [item.nameWidth]}; 

ItemProc: procedure [item: ItemHandie] returns [proc: MenuProc] = 
INLINE {RETURN [item.procj}; 
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MenuArray: procedure [menu: MenuHandie] returns [array: ArrayHandle] = 
INLINE {RETURN [menu.array]}; 

MenuTitle: procedure [menu: MenuHandie] returns [title: ItemHandle] = 
INLINE {RETURN [menu.title]}; 

Note: MenuObjects and Items are private records that are of use to menu posters, but not 
of interest to general clients. The private records shown below are purely informative in 
nature. 



Privateltem: TYPE » private record [ 
proc: MenuProc, 
nameWidth: natural, 
nameBytes: natural, 
body: select hasltemData: boolean from 
FALSE as > [name xstring.ByteSequencel, 

TRUE a > [itemData: long unspecified, name: xstring.ByteSequencel 
endcase]; 



PrivateMenu: TYPE = private record [ 
zone: uncounted zone, 
swapltemProc: SwapltemProc, 
title: ItemHandle <-nil, 
array: ArrayHandle nil, 
arrayAllocatedltemHandles: natural <— 0, 
itemslnMenusZone: boolean <- false]; 



31.3 Usage/Examples 



A menu is displayed to the user by a mechanism outside the scope of this interface. A 
given menu instance cannot ordinarily be displayed more than once at the same time. 



When the user asks that a command be executed, the command item's procedure is called. 
The argument is a pointer that is dependent on the display mechanism; it might be the 
StarWindowShell.Handle that the menu is posted in. 



31.3.1 Example 1. 



sysZ: UNCOUNTED ZONE = Heap.systemZone; 
Init: PROC = { 

sampleTool: xstring.ReaderBody ^xstring.FromSTRING["SampleTool"L]; 
Attention.AddMenultem [ 
MenuData. Createltem [ 

zone: sysZ, • 

name: ©sampleTool, 

proc: MenuProc] ] }; 

MenuProc: MenuData-MenuProc = { 

another: xstring.ReaderBody <-xstring.FromSTRING["Another"L]; 
repaint: xstring.ReaderBody <-xstring.FromSTRING["Repaint"Ll; 
post: xstring.ReaderBody <-xstring.FromSTRING["Post A Message"L]; 
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sampleTool: xstring.ReaderBody ^xstrmg.FromSTRING["Sample Toor'L]; 
" Create the StarWindowShell. — 

shell: starwindowSheii. Handle = StarWindowShell. Create [name: @sampleTool]; 



— Create some menu items. - 

z: UNCOUNTED ZONE <-starwindowSheiLGetZone [shell]; 

items: array [0..3) OF MenuOata.ltemHandle [ 

MenuData.Createltem [zone: z, name: ©another, proc: MenuProc], 
MenuData.Createltem [zone: z, name: ©repaint, proc: RepaintMenuProc], 
MenuData.Createltem [zone: z, name: ©post, proc: Post] ]; 

myMenu: MenuData.MenuHandle s MenuData.CreateMenu [ 
zone: z, 
title: NIL, 

array: descriptor [items] ]; 
StarWindowShell. SetRegularCommands [sws: shell, commands: myMenu]; 



}; 

Post: MenuData.MenuProc = { 

msg: xstring.ReaderBody ^xstring.FromSTRING ["This is a sample attention window 
message. "Lj; 
Attention. Post [@msg] }; 

RepaintMenuProc: MenuData.MenuProc = { 

body: Window. Handle s starWindowSheli.GetBody[[window]]; 
window.lnvalidateBox[body, [[0, 0], [30000, 30000] ]]; 
Window. Validate[body] }; 

~ Mainline code — 

lnit[]; 



31.3.2 Example 2 

~ Declare and create an item title and command array to be placed in a menu — 
mouseMenuTitle: MenuOata.ltemHandle <— InitMouseMenuTitle []; 
mouseMenuCmnds: array [0..10) OFMenuData.ltemHandle; 

-- Create the menu 

mouseMenu: MenuData.MenuHandle <— MenuData.CreateMenu [ 
zone: MenuOata.PublicZone [],-- could be a client-supplied zone - 
title: mouseMenuTitle, 

array: descriptor [@mouseMenuCmnds[0], 1] ]; 
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CommandProc: MenuData.MenuProc = { 

—does something reasonable for the corresponding item — }; 



InitMouseMenuTitie: PROCEDURE RETURNS [MenuData.itemHandle] » { 
zone: uncounted zone <-MenuOata.PublicZone []; 
mouseBitMap: array [0..15) ofword<- [ ... octal code -- 1; 
mouseSymbolChar: xstring.Character <r- 

SimpieTextFont.AddClientDefinedCharacter [ — ... parameters — ]; 
mouseString: xstring.ReaderBody ^xstring.FromChar [@mouseSymbolChar]; 
cmndTitle: xstring.ReaderBody <~xstring.FromSTRING ["Command"]; 
mouseMenuCmndsfO] <— MenuOata.Createltem [zone, ©cmndTitle, CommandProc]; 
RETURN [MenuData.Createltem [zone, ©mouseString, NIL] ] }; 

The above example is just one technique for initializing a menu. The routine 
InitMouseMenuTitie is used to place variables in the local frame that don't need to be 
global. Close attention should be paid to placement of variables to prevent dangling 
references. 
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31.4 Index of Interface Items 



Item 


Page 


Addltem: procedure 


2 


ArrayHandle: type 


2 


Createltem: procedure 


1 


CreateMenu: procedure 


2 


Destroyltem: procedure 


2 


DestroyMenu: procedure 


2 


Item: type 


1 


ItemData: procedure 


3 


ItemHandle: type 


1 


Item Name: procedure 


3 


ItemNameWidth: procedure 


3 


ItemProc: procedure 


3 


MenuArray: procedure 


4 


MenuHandle: type 


2 


MenuObject: type 


2 


MenuProc: type 


1 


MenuTitle: procedure 


4 


Privateltem: type 


4 


PrivateMenu: type 


4 


PublicZone: procedure 


2 


SetltemNameWidth: PROCEDURE 


3 


SetSwapltemProc: procedure 


3 


Subtractltem: PROCEDURE 


3 


Swapltem: procedure 


3 


SwapltemProc: type 


3 


UnpostedSwapltemProc: SwapltemProc 


3 
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32.1 Overview 



MessageWindow provides a facility for posting messages to the user in a window. This is 
similar to posting messages using the Attention interface, but there can be many message 
windows on the screen at once, while there is only one attention window. A message 
window is usually a short window with less than 10 lines of text in it. As more messages 
are posted, previous messages scroll off. 

MessageWindow.Create takes a "plain" window, typically obtained by calling 
StarWindowShell.CreateBody or FormWindow.MakeWindowltem, and turns it into a message 
window. Messages may then be posted by calling Post. The window can be cleared by 
calling Clear. Various types may be formatted into messages to be posted in the window by 
using the XFormat. Object returned by XFormatObject. 



32.2 Interface Items 



32.2.1 Create, Destroy, etc. 



Create: procedure [window: window. Handle, 

zone: uncounted zone <- nil, lines: cardinal <~ 10]; 

Create turns window into a message window, zone will be used for storage of any strings 
posted. If zone is nil, a private zone is used, lines is the number of lines of text to display. 
After more than lines of text are posted, the oldest lines are scrolled out of the window. Fine 

Point: The current ViewPoint implementation does not support user scrolling. 

Destroy: procedure [window. Handle]; 

Destroy turns the window back into an ordinary window, destroying any 
MessageWindow specific context associated with the window. It does not destroy the 
window. 

Isit: procedure [window.Handle] returns [yes: boolean]; 

Isit returns true if the window was made into a message window by a call to Create. 
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32.2.2 Posting messages 




Post: PROCEDURE [window: window. Handle, 
r: xstring.Reader, clear: boolean true]; 

Post displays r in window. If clear is true, r starts on a new line. If clear is false, r is 
appended to the last line posted. 

PostSTRING: PROCEDURE [window: window.Handle, 

S: LONG STRING, clear: BOOLEAN <- true] « INLINE 
BEGIN 

r: xstring.ReaderBody <-xstring.FromSTRING [s]; 
MessageWinddw.Post [window, @r, clear]; 
end; 

PostSTRING posts s in window. If clear is true, r starts on a new line. If clear is false, r is 
appended to the last line posted. 

Clear: procedure [window: window.Handle]; 

Clear clears the entire window. 

XFormatObject: procedure [window: window.Handle] returns [o: xFormat.Object]; 



XFormatObject returns an XFormat.Object that can be used to post messages in window. 
The format procedure logically calls Post with clear a false. See examples. 




32.3 Usage/Examples 

The following example has a client displaying the name and size of a file. It uses the NSFile 
interface to access the file and get the name and size attributes. See the Services 
Programmer s Guide - 610E00180 - Filing Programmer's Manual for documentation on 
the NSFile interface. The example intermixes use of the format handle and use of the Post 
procedure. 



msgW: window.Handle ^-FormWindow.MakeWindowltem [. . .]; 
MessageWindow.Create [window: msgW, lines: 5]; 

PostNameAndSize [file, msgW]; 



PostNameAndSize: procedure [file: NSFiie.Handle, msgW: window.Handle ] = { 
nameSelections: NSFiie.Selections = [interpreted: [name: true]]; 
attri butes : NSFiie. Attr i butesRecord ; 

msgWFormat: XFormat.Object <-MessageWindow.XFormatObject[msgW]; 
rb: xstring.ReaderBody *- Message[theFile]; 

Messagewindow.Post[window: msgW, s: @rb, clear: true]; -- start a new message 
xFormat.NSString[@msgWFormat, attributes. name]; 
XFormat.ReaderBody[h: ©msgWFormat, rb: Message[contains]]; 
XFormat.Decimal[h: ©msgWFormat, n; NSFile. GetSizelnBytes[file]]; 
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rb *- Messagefbytes]; 

Messagewindow.Post[winclow: msgW, s: @rb]}; - clear defaults to true 

Message: procedure [key: {theFlle, contains, bytes}] returns [xstring.ReaderBody] = { 
" ...}; 

An example of the resulting message displayed in the message window is 
The file Foo contains 53324 bytes 
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32.4 Index of Interface Items 



Item 


Page 


Clear: type 


2 


Create: procedure 


1 


Destroy: type 


1 


Isit: TYPE 


1 


Post: TYPE 


2 


PostSTRING: type 


2 


XFormatObject: type 


2 
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33.1 Overview 

OptionFile reads values from profile files (text files) with the following format: 
[Section] 

Entryl: TRUE -- a boolean entry 

Entry2: A string value 

Entry 3: 123 ~ an integer entry 

These files are primarily used for keeping user options across logon and boot sessions (thus 
the name profile file). Applications will typically read various options out of the current 
user profile file at logon. These options often specify default values for properties and/or 
behavior of the application. 



33.2 Interface Items 



33.2.1 Getting Values from a File 

Each GetXXXValue procedure takes a section name and an entry name that identifies the 
entry. It is expected that the section and entry strings will be obtained from XMessage. 
Each also takes a file. If file is defaulted, the current user profile is used (see the Current 
Profiles section below). All these procedures may raise Error linvalidParameters, 
inconsistentValue, notFound, syntaxError]. 

GetBooleanValue: procedure [section, entry: xstring.Reader, 
file: NSFlle.Reference <-NSFiie.nullReferencel 
RETURNS [value: boolean]; 

GetBooleanValue returns the value of a boolean entry. The entry must contain either 
"TRUE" or "FALSE" or the translated string for true or FALSE as defined in the message 
flies. 

GetlntegerValue: procedure [section, entry: xstring.Reader, 

index: cardinal <f- 0, file: NSFiie. Reference NSFiie.nullReference] 
returns [value: long integer]; 
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GetlntegerValue returns the value of an integer entry. The entry must contain a number 
that can be parsed by xstring.ReaderToNumber. index causes the indexth entry to be read, 
for repeating entries. 

GetStringValue: procedure [section, entry: xstring. Reader, 

callBack: procedure [value: xstring.Reader], index: cardinal <-0, 
file: NSFiie. Reference «-NSFiie.nullReferenceI; 

GetStringValue calls callBack with the value of a string entry, index causes the indexth 
entry to be read, for repeating entries. 

33.2.2 Current Profiles 

ViewPoint supports a current User profile file and a Workstation profile file. The current 
User profile is automatically changed whenever a user logs on or off. The Workstation 
profile contains entries specific to the workstation rather than specific to each user. There 
is one Workstation profile on each workstation. 

GetUserProfile: procedure returns [file: NSFiie. Reference]; 

GetUserProfile returns the current User profile file. Note: Each of the Get and Enumerate 
procedures will use this file as the file parameter is defaulted. 

GetWorkstationProfile: procedure returns [file: NSFiie.Reference]; 

GetWorkstationProfile returns the current Workstation profile file. 

33.2.3 Enumerating a File 

EnumerateXXX are useful for applications that look for the same entry in all sections. 

EnumerateSections: procedure [callBack: SectionEnumProc, 
file: NSFiie.Reference <-NSFiie. nullReferencel; 

SectionEnumProc: TYPE a procedure [section: xstring.Reader] 

RETURNS [stop: BOOLEAN FALSE]," 

EnumerateSections will call callBack for each section in file, until stop = true. If file is 
defaulted, the current user profile is used. 

EnumerateEntries: procedure [section: xstring.Reader, callBack: EntryEnumProc, 
file: NSFiie.Reference <-NSFiie.nullReference]; 

EntryEnumProc: type = procedure [entry: xstring.Reader] 
returns [stop: boolean false]; 

EnumerateEntries will call callBack for each entry in section in file, until stop = true. If 
file is defaulted, the current user profile is used. 
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33.2.4 Errors 

Error: ERROR [code: ErrorCode]; 

ErrorCode: type = {invalidParameters, inconsistentValue, notFound, syntaxError}; 
invalidParameters such as passing in a nil string. 

inconsistentValue calling GetBooleanVaiue for an entry that does not have true 
or FALSE as its value, or calling GetlntegerValue for an entry 
that will not parse as number. 

notFound asking for an entry that is not in the file. 

invalidFiie reading from a file that is not a profile file 

syntaxError garbage in the file. 

NotAProfileFile: signal; 

The passed file is not a profile file; that is it has the wrong file type. RESUMEing will read 
the file anyway. 

33.3 Usage/Examples 

— In global frame 
displayMessage: BOOLEAN true; 

whereToDisplay: SampleBWSApplicationops.WhereToOlsplay ^window; 
messageToDisplay: xstring.Reader <-nil; 

" Called from initialization code 
GetOptionsAtLogon: procedure = { 

logon: Atom.ATOM Atom.MakeAtom["Logon"Ll; 

desktopRef : NSFiie. Reference; 

[] <- Event.AddDependency [agent: LogonEvent, myData: nil, event: logon]; 

if (desktopRef <-> starOesktop.GetCurrentDesktopFile []) # NSFiie.nuilReference then { 

- If the desktop is NOT null, then a user's already logged on, 

—i.e., we got loaded after logon. 
So we go read the options immediately by calling our 

— Event.AgentProcedure directly. — 

desktop: NSFile.Handle <-NSFiie.OpenByReference [desktopRef]; 

[] <- LogonEvent [event: logon, eventData: loophole [desktop], myData: NIL]; 

NSFiie.Ciose [desktop]; 

}; 

}; 

LogonEvent: Event.AgentProcedure = { 

<< [event: Event.EventType, eventData: long pointer, 
myData: long pointer] 

RETURNS [remove: boolean <- false, veto: boolean false] > > 

OPEN Ops: SampieBWSApplicationOps; 

mh: XMessage.Handle a ops.GetMessageHandle[]; 
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CopyMessageToDisplay: procedure [value: xstring.Reader] = { 
messageToDisplay xstring.CopyReader [value, sysZ]}; 

GetWhereToDisplay: procedure [value: xstring.Reader] = { 

window: xstring.ReaderBody <— XMessage.Get [mh, Ops.kwindow]; 
attention: xstring.ReaderBody <- XMessage.Get [mh, Ops.kattention]; 
both: xstring.ReaderBody <- XMessage.Get [mh, Ops.kboth]; 
whereToDispiay <- select true from 

xstring. Equivalent [value, ©window] s > window, 

xstring. Equivalent [value, ©attention] = > attention, 

xstring.Equivalent [value, @both] a > both, 

endcase s > window; 

}; 

section: xstring.ReaderBody XMessage.Get [mh, Ops.kApplicationName]; 

entry: xstring.ReaderBody <- XMessage.Get [mh, ops.kOisplayMessage]; 
displayMessage <-optionFiie.GetBooleanValue [©section, ©entry ! 
optionFiie.Error = > continue]; 

entry <— XMessage.Get [mh, ops.kMessageToOispiay]; 
optionFiie.GetStringValue [©section, ©entry, CopyMessageToDisplay ! 
OptionFiie.Error s > continue]; 

entry <- XMessage.Get [mh, Ops.kWhereToOispiay]; 
optionFiie.GetStringValue [©section, ©entry, GetWhereToDisplay ! 

OptionFiie.Error = > CONTINUE]; 

}; 
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33.4 Index of Interface Items 



Item Page 

EntryEnumProc: type 2 

EnumerateEntries: procedure 2 

EnumerateSections: procedure 2 

Error: error 3 

ErrorCode: type 3 

GetBooleanValue: procedure 1 

GetlntegerValue: procedure 1 

GetStringValue: procedure 2 

GetUserProfile: procedure 2 

GetWorkstationProfile: procedure 2 

NotAProfileFile: signal 3 

SectionEnumProc: type 2 
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34.1 Overview 



The PopupMenu interface provides a single procedure that posts a popup menu. 



34.2 Interface Items 



Popup: PROCEDURE ( 

menu: MenuOata.MenuHandle, 
clients :window.Handie, 
showTi'tle: boolean true, 
place: window. Place <- [-1,-1] ]; 



This procedure causes the display of the client's menu at or near the indicated place in the 
rootWindow; if the place [-1,-11 is given, the current cursor position is used. If the point 
button goes up while the cursor is over one of the menu items, then that item's 
MenuData.MenuProc is called, clients will be passed to the MenuData.MenuProc as the 
window parameter. The showTitle field indicates whether the menu's title should be 
displayed above its command-strings. 

The implementation assumes that the "point" button is down; consequently, the menu is 
displayed until the "point" button goes up Popup does not return until the menu is taken 
down, regardless of whether a menu item is selected or not. 



34.3 Usage/Examples 

Much of the complication in using the PopupMenu interface stems from its reliance on 
MenuData. A thorough understanding of how to create a menu is needed before using this 
interface (see the MenuOata chapter for details). 



34.3.1 Example 



— Create the menu: 

myMenu: MenuOata.MenuHandle ^MenuData. CreateMenu [ 
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- ..." pass in miscellaneous parameters; see the MenuData interface for details 

1; 

PopupMenu. Popup[ 
menu: myMenu, 
clients: currentWindow]; 
- showTitle and place are defaulted in this call. 
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34.4 Index of Interface Items 

Item Page 

Popup: PROCEDURE 1 
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ProductFactoring 



35.1 Overview 

ProductFactoring allows an application to determine whether the customer has purchased 
the application for the workstation the application is running on. ProductFactoring 
maintains a record of the applications that have been purchased (enabled) on the 
workstation's disk. Tools are provided to customers for enabling various applications 
(options). The enabling of an application is outside the scope of this interface. 

ProductFactoring also allows an application to register a name for its product option, thus 
allowing the product factoring tools to display meaningful names to the user of the tools. 

35.2 Interface Items 

35.2.1 Products and ProductOptions 

Product: TYPE = cardinal [0.. 16); 

A Product refers to a large set of software, (also see the ProductFactoringProducts 
interface.) 

ProductOption: TYPE = cardinal [0..28); 

A ProductOption refers to a particular piece of software that a customer can buy within a 
Product, such as Spreadsheets, Advanced Star Graphics, or Print Service. To obtain a 
ProductOption for a particular application, see your Xerox Sales Represenative. 

Option: type » record [product: Product, productOption: ProductOption]; 

nullOption: Option = . . . ; 

An Option uniquely identifies a ProductOption within a Product. 

35.2.2 Checking for an Enable Option 

Enabled: procedure [option: Option] returns [enabled: boolean]; 
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Enabled returns true if option is enabled on this workstation, otherwise false. Typically, 
an application will call Enabled every time it is called to perform some user operation such 
as opening an icon. Enabled is fast; it does not read the file every time it is called. It may 
raise ErrorfnotStarted] if there is no product factoring file on the workstation. 

33.2.3 Describing an Product and an Option 

DescribeProduct: procedure [product: Product, desc: xstring.Reader]; 

Provides a name for product, desc will be copied to an internal zone. May raise 
Error[illegalProduct] if the value of product is out of range. 

OescribeOption: procedure [option: Option, desc: xstring.Reader, 
prerequisite: Prerequisite *- nullPrerequisite]; 

Prerequisite: TYPE = record [ 

prerequisiteSpec: boolean*- false, 
option: Option]; 

nullPrerequisite: Prerequisite = [false, nullOption]; 

Describes option, desc is a name for the option, prerequisite specifies any other options 
that this option depends on. All data will be copied to an internal zone. Use of this 
procedure overrides any earlier definition with the same option value. May raise 
Error[illegaiProduct] if the value of option. product is out of range. May raise 
Error(illegalOptionl if the value of option. productOption is out of range. May raise 
Error[missingProduct] if option. product has not yet been defined. 



35.2.4 Errors 

Error: error [type: ErrorType]; 

ErrorType: type = { 

dataNotFound, notStarted, illegalProduct, illegalOption, 
missingProduct, missingOption}; 



dataNotFound 
notStarted 
illegalProduct 
illegalOption 



The term dataNotFound means the product data file is missing. 
The term notStarted means Start proc has not been called yet. 
The term illegalProduct means not a legal Product value. 
The term illegalOption means not a legal ProductOption value. 



missingProduct The term missingProduct means the Product specified has not yet been 
defined. 



missingOption 



The term missingOption means the ProductOption specified has not 
yet been defined. 
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-- In global frame — 

sampleApplicationPFOption: ProductFactoring.ProductOption = 27; 

— 27 was chosen arbitrarily for this sample. — 

— A real application should obtain a real ProductOption/ -- 

" Called during initialization — 
InitProductFactoring: procedure = { 

mh: XMessage. Handle = SampieBWSAppiicationops.GetMessageHandle[]; 
rbt XString.ReaderBody <~ XMessage.Get [mh, 

SampleBWSApplicationops.kApplicationName]; 
ProductFactoring.DescribeOption [ 

option: [ product: ProductFactoringProducts.Star, 

productOption: sampleApplicationPFOption], 
desc: @rb]; 

}; 

" GenericProc — 

GenericProc: Containee. GenericProc = { 
IF "ProductFactoring.Enabled [option: [ 

product: ProductFactoringProducts.Star, 
productOption: sampleApplicationPFOption]] then { 
mh: XMessage. Handle <r- SampieBWSApplicationops.GetMessageHandle[]; 
rb: XString.ReaderBody <- XMessage.Get [mh, SampleBWSApplicationops.kNotEnabled]; 
ERROR Containee. Error [@rb]; 

}; 

SELECT atom FROM 

}; 
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35.4 Index of Interface Items 



Item Page 

DescribeProduct: procedure 2 

DescribeOptioniPROCEDURE 2 

Enabled: PROCEDURE 1 

Error: error 2 

ErrorType: type 2 

nullOption: Option 1 

nullPrerequisite: Prerequisite 2 

Option: type 1 

Prerequisite: type 2 

Product: type 1 

ProductOption: type 1 
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36.1 Overview 

ProductFactoringProdcuts defines the ProductFactoring. Products for various Xerox products, 
(see the ProductFactoring interface.) 

36.2 Interface Items 

Product: type a ProductFactoring. Product; 
Star: Product = 0; 

Star defines the Xerox Star workstation product. 
Services: Product = 1; 

Services defines the Xerox network services product. 
Fonts: Product a 2; 

Fonts defines the product for Xerox printer fonts. Fine Point: In Viewpoint, this is in 
ProductFactoringProdcutsExtras. 

Spinnaker: Product = 3; 

Spinnaker defines the Xerox Spinnaker product. Fine Point: in Viewpoint, this is in 
ProductFactoringProdcutsExtras. 
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36.3 Index of Interface Items 



Item Page 

Product: type 1 

Fonts: Product 1 

Services: Product 1 

Spinnaker: Product 1 

Star: Product 1 
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37.1 Overview 

The PropertySheet interface allows clients to create property sheets. A property sheet 
shows the user the properties of an object and allows the user to change these properties. 
Several different types of properties are supported. The most common ones are boolean, 
choice (enumerated), and text. (See Figure 37.1.) 





Done 1 Cancel ^\pply II Defaults j 




Tag 1 BOOLEAN | Suffix 


i 


1 CHOICE 1 jiiiiii 2; 1 CHOICE 3 | 
Tag 1 Text item | 


+ 
T 


Form Window 




h — ► ^ H 





Figure 37. 1 . A Property Sheet 



From a client's; point of view, a property sheet is a Star window shell with a form window 
as a body window. See the StarWindowShell and Form Window interfaces. The 
FormWindow interface especially must be understood in order to create a property sheet. 

A property sheet is created by calling PropertySheet.Create, providing a procedure that will 
make the form items in the form window (a FormWindow. MakeltemsProc), a list of 
commands to put in the header of the property sheet, such as Done, Cancel, and Apply 
(PropertySheet.Menuitems), and a procedure to call when the user selects one of these 
commands (a PropertySheet. Men ultemProc). PropertySheet.Create returns the 
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StarWindowSheli.Handle for the property sheet. When the user selects one of the commands 
in the header of the property sheet, the client's PropertySheet.MenultemProc is called. If the 
user selected Done , for example, the client can then verify and apply any changes the user 
made to the object's properties. 

PropertySheet also provides the capability to create linked property sheets. Several 
property sheets may be logically linked together in the same property sheet shell. This is 
accomplished by changing form windows within a property sheet's Star window shell, and 
having an additional choice item that specifies which form window is currently displyed. 
Linked property sheets are further described in the section on Linked Property Sheets 
below. 



37.2 Interface Items 

37.2.1 Create a PropertySheet (Not a Linked One) 

Create: procedure [ 

formWindowltems: Formwindow.MakeltemsProc, 
menultemProc: MenultemProc, 
size: window. Dims, 

menultems: Menultems *- propertySheetDefauitMenu, 

title: xstring.Reader 4-NiL, 

piaceToOisplay: window.Place <- nuliPlace, 

formWindowltemsLayout:Formwindow.LayoutProc <- nil, 

windowAttachedTo: starWindowsheii.Handle <-[nil], 

giobalChangeProc: FormWindow.GlobalChangeProc ^ nil, 

display: boolean <-true. 

clientData: long pointer «- nil, 

afterTakenDown: MenultemProc ♦-nil, 

zone: uncounted zone <- nil] 

returns [shell: starWindowSheii.Handle]; 

Create creates a property sheet. 

formWindowltems is a client-supplied procedure that is passed a body window of the 
property sheet. It should fill the window with the form items that make up the main body 
of the property sheet. (See the Form Window interface for a full description of how to create 
form items in a window.) 

menultemProc is a client-supplied procedure that is called whenever the user selects one 
of the menu items in the header of the property sheet window. (See §37.2.2 below.) 

size is the preferred size of the property sheet star window shell. 

menultems specifies the menu items that are displayed in the header of the property 
sheet. The default is ? (help), Done, and Cancel. 

title is the title to be displayed in the header of the property sheet. 

placeToDisplay is the preferred location on the screen of the property sheet. If the default 

is taken. Create will calculate the place to display. Jiph^ 

formWindowltemsLayout specifies the desired position of the form items in the ' 
FormWindow. (See Form window. Lay outProc for a full description.). If 
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formWindowltemsLayout is nil, then FormWindow.DefaultLayout of one item per line is 
used 

window AttachedTo is the StarWindowShell that this property sheet is showing 
properties for. If window AttachedTo is not nil, then the user will not be able to close 
window AttachedTo until this property sheet is closed. (See also 
StarWindowShell.Create.host.) 

globaSChangeProc is called if any item in the property sheet is changed, (See 
FormWindow.GlobalChangeProc for a full description). 

display indicates whether the property sheet should actually be displayed on the screen 
(inserted into the visible window tree) or just created but not actually painted on the 
screen (not inserted into the visible window tree). If this is a property sheet for a file (i.e., if 
it is being created as the result of a call to a Containee.GenericProc [atom: Props]), then 
display should be false and the starWindowShell. Handle should be returned from the 
GenericProc so that, for example, the desktop implementation can put the property sheet 
on the display by calling StarWindowShell. Push. 

clientData will be passed to formWindowltems, formWindowltemsLayout, and 

menultemPrOC. Fine Point: formWindowltems will not be called after Create returns and therefore may be 
nested. 

The afterTakenDown is called after the property sheet has been removed from the screen. 
The return parameter of the MenultemProc is ignored in this case. Note: Clients must 
still provide a regular MenultemProc. 

Clients may pass in a zone to be used instead of the default zone created by the 
StarWindowShell implementation. 

shell is the property sheet. 
nullPlace: window. Place; 

nullPlace defines the default for placement of a property sheet. If the default is used, the 
property sheet is placed at an appropriate place on the screen. 

37.2.2 Menu Items and the MenultemProc 

MenultemType: type = {done, apply, cancel, defaults, start, reset}; 
Menultems: type = packed array MenultemType of BooieanFalseDefault. 
BooleanFalseDefault: type = boolean <h- false; 

propertySheetDefaultMenu: Menultems = [done: true, apply: true, cancel: true],- 
optionSheetDefaultMenu: Menultems = [start: true, cancel: true]; 

The client specifies a set of commands to be placed in the header of the property sheet. 
MenultemType specifies all of the possible commands. Menultems specifies a set of these 
commands and is passed to PropertySheet.Create. propertySheetDefaultMenu and 
i_ OptionSheetDefaultMenu specify two common sets of commands. 

MenultemProc: type = procedure [ 

shell: StarWindowSheii.Handle, 
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formWindow: window.Handle, 
menultem: MenultemTypel 

RETURNS [ok: BOOLEAN <- false] ; 

The client supplies a MenultemProc when a property sheet is created. It is called 
whenever the user selects one of the menu items in the header of the property sheet. 
formWindow is the main form window of the property sheet, menultem is the type of 
menu item that the user selected. The client typically (when the user selects Done or 
Apply) retrieves the values of the items that the user edited (using 
FormWindow. HasChanged and FormWindow. GetXXXItemValue procedures), verifies that the 
values are meaningful (for example, numbers that are within proper range), and applies 
the new values to the properties of the object this property sheet represents. 

The return parameter ok has slightly different meanings in the following two cases: 

1. For an ordinary property sheet (not a linked property sheet), the MenultemProc is 
called when the user selects a command and the return parameter indicates whether 
the property sheet should be destroyed. 

2. For a linked property sheet, the MenultemProc is called both when the user selects a 
command in the header (in which the case above applies) and when the client calls 
SwapExistingFormWindows or SwapFormWindows with apply a true. In this case 
the MenultemProc is called to allow the client to apply any changes made to the form 
window sheet being linked from. The menultem parameter will be "done"; the return 
parameter indicates whether to allow the swap to actually occur, ok = false indicates 
that there is something invalid in the form window and the client does not want the 
swap to occur (the client typically posts a message before returning). If ok = true, the 
swap occurs. 

Note: The client need not worry about these cases when writing the MenultemProc, but 
can simply write the "done" code as usual. If the user selects Done and the MenultemProc 
returns ok a TRUE, the property sheet is destroyed. If the user links to another sheet on a 
linked property sheet and the MenultemProc returns ok a true, the sheets are swapped, 
rather than the whole property sheet being destroyed. 

37.2.3 Linked PropertySheets 

Several property sheets may be logically linked together in the same property sheet. This 
is accomplished by changing form windows within a property sheet's Star window shell, 
and having an additional choice item that specifies which form window is currently 
displayed. See Figure 37.2 below. 
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Figure 37.2 A Linked Property Sheet 
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This additional choice item actually resides in an additional form window, called a link 
window. This link window is another body window of the Star window shll. The link 
window remains visible all the time, while the main form window may be swapped. The 
client does this by supplying a FormWindow.ChoiceChangeProc for the single choice item in 
the link window. Then when the user selects a new choice for that item, the client (in the 
ChoiceChangeProc) calls SwapFormWindows or SwapExistingForm Windows to change 
the main form window. Note: Only one main form window is installed in the Star window 
shell at a time. A linked property sheet is created by calling CreateLinked. 



CreateLlnked: procedure [ 

formWindowltems: FormWindow.MakeltemsProc, 
menultemProc: MenultemProc, 
size: window.Dims,, 

menultems: Menultems <r- propertySheetDefaultMenu, 

title: xstring.Reader <-NiL, 

piaceToOisplay: window.Place «- nullPlace, 

formWindowltemsLayout:FormWindow.LayoutProc <- nil, 

windowAttachedTo: starwindowSheii.Handle <~[nil], 

globalChangeProc: Formwindow.GlobalChangeProc <-nil, 

display: boolean <-true, 

linkWindowltems: FormWindow.MakeltemsProc, 

iinkWindowltemsLayout:FormWindow.LayoutProc <- nil, 

clientData: long pointer <-nil. 

afterlakenDownProc: MenultemProc <- nil. 

zone: uncounted zone*- nil] 

returns [shell: starWindowSheii.Handle]; 

CreateLinked creates a linked property sheet. Creating a linked property sheet is almost 
identical to creating an ordinary property sheet, (see Create above for a full description of 
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all the parameters), except Create Linked has the additional parameters linkWIndowltems 
and linkWindowltemsLayout. linkWindowltems is called to make the choice item in the 
link window. It should create a single choice item with a FormWIndow.ChoiceChangeProc. 
linkWindowltemsLayout is called to specify the position of the choice item in the link 
window. The default places the item appropriately in the link window, so most clients will 
want to take the default for linkWindowltemsLayout. Note: formWindowltems and 
formWindowltemsLayout specify the main form window that is initially visible in the 
property sheet. 

SwapFormWindows: procedure [ 
shell: StarWindowShelLHandle, 

newFormWindowltems: FormWindow.MakeltemsProc, 

newFormWindowltemsLayout:FornniWindow.LayoutProc<-Niu 

apply: boolean «- true, 

destroyOld: boolean true, 

newMenultemProc: MenultemProc ♦-nil, 

newMenultems: Menultems <- all(false]. 

newTitle: xstring. Reader <- nil, 

newGlobaiChangeProc: FormWindow.GlobaiChangeProc <-nil. 
newAfterTakenDownProc: MenultemProc <-nil1 
RETURNS [old: window.Handlej; 

SwapForm Windows swaps the main form window of a property sheet with a new one. This 
will usually be called from the FormWfndow.ChoiceChangeProc of the choice item in the link 
window. May raise Error [notAPropSheet]. 

shell is the property sheet. 

newFormWindowltems supplies the items for the new window. 

newFormWindowltemsLayout specifies the layout for the items in the new form window. 

apply specifies whether any changes to the current form window should be applied before 
the swap. If apply = true, the current MenultemProc for shell is called with menultem = 
apply. If apply = false, the MenultemProc is not called. 

The destroyOld parameter indicates whether the old form window should be destroyed or 
not. If destroyOld a false, then the return parameter is the old form window, else the 
return parameter is nil. This allows clients to perform the following typical sequence of 
events: 

1. Create a linked property sheet using CreateLinked. 

2. The first time the user links to another sheet, call SwapFormWindows with 
destroyOld « false and save the old form window. 

3. When the user goes back to the first sheet, call SwapExistingFormWindows, 
supplying the previously saved old form window, and thus avoiding having to create 
the first form window again. 

newMenultemProc allows the client to install a different MenultemProc than the one that 
was supplied with CreateLinked. 

newAfterTakenDownProc allows the client to install a different takedown MenultemProc 
than the one that was supplied with CreateLinked. 
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newMenultems, newTitle, and newGlobalChangeProc allow the client to change these as 
well. 

If the default newMenultemProc, newMenultems, newTitle, or newGlobalChangeProc is 

taken, the current values are retained. 

SwapExistingFormWindows: procedure [ 
shell: StarWindowSheil.Handle, 
new: window. Handle, 
apply: boolean true, 
newMenultemProc: MenultemProc <-nil, 
newMenultems: Menultems <- all(false]. 
newTitle: xstring.Reader <~ nil. 
newAfterTakenDownProc: MenultemProc ♦-nil] 
RETURNS [old: Window. Handle]; 

SwapExistingFormWindows swaps the main form window of a property sheet with a new 
one. The new form window must already exist. If it does not, use SwapFormWindow, new 
is the new form window, apply, newMenultemProc, newMenultems, and newTitle are the 
same as in SwapFormWindow. old is the previous main form window. May raise Error 
[notAPropSheet]. 

37.2.4 Miscellaneous 

GetFormWindows: procedure [shell: starWindowSheii. Handle] 
RETURNS [form, link: window.Handlel; 

GetFormWindows returns the current form windows of shell. If shell is not a linked 
property sheet, link is nil. May raise Error [notAPropSheet]. 

InstallFormWindow: procedure [ 
shell: StarWindowSheil.Handle, 
menultemProc: MenultemProc, 

menultems: Menultems propertySheetDefaultMenu, 
title: xstring.Reader <- NIL, 
formWindow: window.Handle, 
afterTakenDownProc: MenultemProc «- nil]; 

InstallFormWindow installs formWindow in shell. May raise Error [notAPropSheet]. 

37.2.5 Signals and Errors 

Error: error [code: ErrorCode]; 
ErrorCode: type = {notAPropSheet}; 

Error [notAPropSheet] is raised if a StarWindowSheil.Handle that is not a property sheet is 
passed to a PropertySheet procedure . 
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37.3 Usage/Examples 

37.3.1 Flow Description of Creating a Property Sheet 

The following describes the sequence of calls involved in creating and taking down a 
property sheet, including ViewPoint interfaces and clients. 

1. Client calls PropertySheet.Create, supplying a FormWindow.MakeltemsProc, a 
FormWindow.LayoutProc (optional), and a PropertySheet.MenultemProc. 

2. PropertySheet.Create creates a Star window shell and a body window inside the 
StarWindowShell. It then calls FormWindow.Create, passing in the body window. 

3. FormWindow.Create calls the client's FormWindow.MakeltemsProc. 

4. The client's FormWindow.MakeltemsProc creates the items in the property sheet by 
calling various Form window. MakeXXXItem procedures. 

5. FormWindow.Create calls the client's FormWindow.LayoutProc. If the client did not 
provide one, a default LayoutProc provided by FormWindow is called. 

6. The FormWindow.LayoutProc makes calls to FormWindow.AppendLine and 
FormWindow.Appendltem to specify the layout of the items created by the 
FormWindow.MakeltemsProc. 

7. FormWindow.Create returns to PropertySheet.Create. PropertySheet.Create returns to the 
client. The client returns to the notifier process. 

8. The property sheet is now on the screen and the notifier process is waiting for the user. 

9. The user changes some values in the property sheet. This is all managed by 
FormWindow; the client gets called only if there is a FormWindow. BooieanChangeProc 
or FormWindow. ChoiceChangeProc or FormWindow. GiobaiChangeProc. 

10. The user selects Done in the header of the property sheet. 

11. A procedure inside of PropertySheet is called. PropertySheet calls the client's 
PropertySheet.MenultemProc 

12. The client's PropertySheet.MenultemProc checks for any changed values 
(FormWindow. HasBeenChanged and FormWindow. HasAnyBeenChanged) and calls the 
appropriate FormWindow. GetXXXItemValue to obtain the new values. The client 
validates and applies these new values, then returns an indication of whether the 
property sheet should be taken down. 

13. PropertySheet takes down the property sheet and returns to the notifier. 



14. END. 
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37.3.2 An Ordinary Property Sheet 

This example creates a property sheet from some arbitrary properties and then applies the 
user's changes to those properties. It uses a rather contrived set of properties described by 
Properties and PropertiesObject. In general, a real property sheet would get its properties 
from some real object. This example will produce the property sheet shown in Figure 37.1. 

- PropertySheetExample.mesa 

DIRECTORY 

FormWindow using [ 

Choiceftem, GetBooleanltem Value, GetChoiceltemValue, GetTextltemValue, 
HasAnyBeenChanged, HasBeenChanged, ItemKey, MakeBooleanltem, 
MakeChoiceitem, MakeltemsProc, MakeTextltem, SetBooleanltemValue, 
SetChoiceitem Value, SetTextltemValue], 

PropertySheet using [Create, MenultemProc]„ 

StarWindowShell using [Handle], 

XString using [FreeReaderBytes, FromSTRING, ReaderBody], 
Window using [Handle]; 

PropertySheetExample: program imports FormWindow, PropertySheet, XString = { 

Properties: TYPE = long pointer to PropertiesObject; 

PropertiesObject: TYPE a RECORD [ 
boolean: BOOLEAN, 
choice: Choices, 
text: XString. ReaderBody]; 

Items: TYPE = {boolean, choice, text}; 

Choices: TYPE a {choicel, choice2, choices}; 

zone: uncounted zone <-.,.; 

MakePropertySheet: procedure [props: Properties] 
RETURNS [shell: StarWindowShell. Handle] - { 
title: xstring.ReaderBody <H-xstring.FromSTRING ["Title"L]; 

shell PropertySheet.Create [ 

formWindowltems: Makeitems, 

menultemProc: MenultemProc, 

menultems: [help: true, done: true, cancel: true, 

apply: true, defaults: true], 
size: [w: 300, h: 200], 
title: ©title, 
clientData: props]; 

}; 
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Makeltems: FormWindow.MakeltemsProc = { j^^^ 
props: Properties *-clientData; j 
tag: XString.ReaderBody <-xstring.FromSTRING["Tag"L]; 

BEGIN 

label: xstring.ReaderBody <-xstring.FromSTRING{"BOOLEAN"L]; 
suffix: xstring.ReaderBody <-xstring.FromSTRING["suffix"L]; 
FormWindow.MakeBooleanltem [ 

window: window, 

myKey: Items. boolean.ORO, 

tag: @tag, 

suffix: ©suffix, 

label: [string [label] ], 

initBoolean: props. boolean ]; 
end; 

BEGIN 

c1 : xstring.ReaderBody <-xstring.FromSTRING["CHOICE 1"L]; 
c2: xstring.ReaderBody <-xstring.FromSTRING["CHOICE 2"L]; 
c3: xstring.ReaderBody <-xstring.FromSTRING["CHOICE 3"L]; 
choices: array [0..3) of FormWindow.Choiceltem [ 

[string[Choices.choice1.0RD, c1] ], 

[string[Choices.choice2.0RD, c2] ], 

[string(Choices.choice3.0RD, c3] ] ]; 
Formwindow.MakeChoiceltem [ 

window: window, j 

myKey: Items.choice.ORD, 

values: DESCRiPTOR[choices], 

initChoice: props. choice. ord]; 
end; 

Formwindow.MakeTextltem [ 
window: window, 
myKey: Items.text.ORD, 
tag: @tag, 
width: 40, 

initString: ©props.text 1; 

}; 

MenultemProc: PropertySheet.MenultemProc = { 
props: Properties <e- clientData; 
SELECT menultem from 
help = >...; 

done = > RETURN[destroy: ApplyAnyChanges[formWindow, propsj.ok]; 
cancel a > RETURN[destroy: true]; 

apply a > [] ♦-ApplyAnyChanges[formWindow, props]; 
defaults « > SetDefaults[formWindow, props]; 

ENDCASE = > error; 

RETURN[destroy: false]; | 

}; 
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ApplyAnyChanges: proc [window: window.Handle, props: Properties] 

RETURNS [0l<: boolean] s BEGIN 

IF -FormWindow.HasAnyBeenChanged [window] then return [ok: true]; 
FOR eaclilteim: Items in Items do 

itemKey: FormWindow.ltemKey = eachltem.ORD; 

IF -FormWindow.HasBeenChanged [window, itemKey] then loop; 

SELECT eachltem from 

boolean = > props.boolean «-FormWindow.GetBooleanltemValue[window, itemKey]; 
choice a > props. clioice <-VAL[FormWindow.GetChoiceltemValue[window, itemKey] ]; 
text = > { 

xstring.FreeReaderBytes (r: @props.text, z: zone]; 
props. text <—FoirmWindow.GetTextltemValue [window, itemKey, zone]}; 
endcase; 

ENDLOOP; 

return [ok: true]; 

end;- ApplyAnyChanges 

SetDefaults: proc [window: window.Handle, props: Properties] = 

BEGIN 

defaultText: xstring.ReaderBody <-xstring.FromSTRING["Text item"L]; 
FormWindow.SetBooleanltemVaiue [ 

window: window, 

item: Items.boolean.ORO, 

newValue: false ]; 
FormWindow.SetChoiceltemValue [ 

window: window, 

item: Items.choice.ORO, 

newValue: Choices.choice2.0RD]; 
Formwindow.SetTextltemValue [ 

window: window, 

item: Items.text.ORO, 

newValue: ©defaultText]; 
end; 

}... 
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37.4 Index of Interface Items 



Item Page 

BooleanFalseDefault: type 3 

Create: procedure 2 

CreateLinked: procedure 5 

Error: error 7 

ErrorCode: type 7 

GetFormWindows: procedure 7 

instailFormWindow: procedure 7 

MenultemProc: type 4 

Menultems: type 3 

MenultemType: type 3 ° 

nul (Place : window.Place 3 

optionSheetDefaultMenu: Menultems 3 

propertySheetDefaultMenu: Menultems 3 

SwapExistingFormWindows: procedure 7 

SwapFormWindows: procedure 6 



Prototype 



38.1 Overview 

Prototype manipulates prototype files. A prototype file is a blank copy of an application's 
file that the user can copy. Prototype files are in the Directory icon under "Blank 
Documents, Folders, etc." 

A prototype file resides in the prototype catalog (see the Catalog interface) and is uniquely 
identified by it is file type, subtype, and version. Subtype is used to distinguish between 
objects of the same file type, such as the blank document and the basic graphics transfer 
document. Subtype is stored in an extended attribute on the prototype file. A nonexistent 
subtype is equivalent to subtype 0. 

Version is stored in the BWS-standard version extended attribute (see 
BWSAttributeTypes). The intent is that clients need only examine the version to 
determine if the prototype is current. A nonexistent version attribute is equivalent to 
version 0. 

Prototype provides Find and Create procedures. A client will typically call Find and if it 
returns NSFile.nullReference, then call Create. 

38.2 Interface Items 

Version: type a cardinal; 
Subtype: type a cardinal; 

Find: procedure [type: NSFileType, version: Version, 

subtype: Subtype «-0, session: NSFiie. Session <-NSFiie.nullSession] 
RETURNS [reference: NSFiie.Reference]; 

Find returns a reference for the file with the specified type, version, and subtype. If the 
file does not exist, NSFiie. nullReference is returned. 

Create: procedure [ 

name: xstring.Reader, 
type: NSFile.Type,, 
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version: Version, 

subtype: Subtype <- 0, 

size: long cardinal <- 0, 

isDirectory: boolean*- false, 

session: NSFUe. Session *-NSFiie.nullSession] 

RETURNS [prototype: NSFile. Handler- 
Creates a file in the prototype catalog with the specified name, type, version, subtype, 
size in bytes, and isDirectory attribute. 

Add: PROCEDURE [file: NSFiie.Handle, version: Version, 

subtype: Subtype <-0, session: NSFiie. Session 4-NSFile.nuilSession]; 

Moves an already existing file into the prototype catalog, assigning it the given version 
and subtype. Fine Point: This is in Prototype Extra in ViewPoint. 

PurgeOldVersions: procedure (type: NSFiie.Type, current: Version, subtype: Subtype «- 0]; 

Deletes any versions of the given prototype that are older (smaller number) than current. 
PurgeOldVersions assumes that higher version numbers are more recent than lower 
version numbers. If this is not true for your version numbers, do not call this operation . 



This is an example of a procedure that an application would probably call at initialization 
time. 

samplelconFileType: NSFiie.Type a . . . ; 

version: cardinal = . . . ; 

FindOrCreatelconFile: procedure = { 

name: xstrlng.ReaderBody «- xstring.FromSTRING["Sample lcon"L]; 
-- This name should really come from XMessage. 
IF (Prototype.Find [ 

type: samplelconFileType, version: version] = NSFiie.nullReference) then 
NSFiie.Close [Prototype. Create [ 



38.3 Usage/Examples 



name: ©name, type: samplelconFileType, version: version] ]; 



}; 
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38.4 Index of Interface Items 



Item 


Page 


Add: PROCEDURE 


2 


Create: procedure 


1 


Find: procedure 


1 


PurgeOldVersions: procedure 


2 


Subtype: type 


1 


Version: type 


1 
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39,1 Overview 

The Selection interface defines the abstraction that is the user's current selection. It 
provides a procedural interface to the abstraction that allows it to be set, saved, cleared, 
and so forth. It also provides procedures that enable someone other than the originator of 
the selection to request information relating to the selection and to negotiate for a copy of 
the selection in a particular format. 

39.1.1 Requestors and Managers 

The Selection interface is used by two different classes of clients. Most clients wish merely 
to obtain the value of the current selection in some particular format; such clients are 
called requestors. These programs call Convert (or ConvertNumber, which in turn calls 
Convert), Query, or Enumerate, These clients need not be concerned with many of the 
details of the Selection interface. 

The other class of clients consists of those who wish to own or set the current selection; 
these clients are called managers. A manager calls Selection.Set and provides procedures 
that may be called to convert the selection or to perform various actions on it. The 
manager remains in control of the current selection until some other program calls 
Selection.Set. These clients do need to understand most of the details of the Selection 
interface. 

The goal of the Selection interface is that the requestor need never know, and should 
never care, what module is managing the selection. All that matters is whether the 
selection can be rendered in a suitable form. For example, suppose the user presses COPY 
and selects a printer icon as the destination. The printer implementation needn't know 
what is printable and what isn't. It simply queries the selection to determine whether it 
can be rendered as an Interpress master, and if so it obtains it and sends it. Otherwise, it 
queries whether the selection can be enumerated as a sequence of Interpress masters (as 
would be true of a folder, for instance). If this also fails, the object is rejected. 

The selection is the expression of the user indicating the datum to be operated on. As such, 
it is conceptually owned by the user. The selection manager is a slave following the user's 
instructions. 
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To maintain this user interface model, the selection must only be changed at the explicit 
direction of the user. Software must allow the user to change the selection at will. To 
implement this user model, the selection is only changed from within the user process or 
notifier. The notifier is the system process that passes the user's actions, encoded as TIP 
results, to application software. 

Software that wishes to read the selection must deal with the fact that the selection may 
be changed at any time that the notifier process is running. The way to synchronize with 
this potentially asynchronous activity is to only read the selection in the notifier process. 
This guarantees that the selection will not be altered while it is being read. Application 
software running in the notifier process can be assured that the selection will not change 
until after the application returns to the system. Thus the first rule for dealing with the 
selection is: 

The selection may only be read or changed in the notifier process. 

Once an application returns to the notifier, any knowledge it retains about the selection 
may be invalidated at any instant when the user subsequently changes the selection. 
Similarly, if an application running in the notifier passes some information about the 
selection to another process, that information may similarly be invalidated at any time. In 
these circumstances, the application must copy the selection's value, using Copy, Move, or 
CopyMove, to assure that its data remains valid. Thus the second rule for dealing with the 
selection is: 

Copy the selection's value before returning to the system or before passing it to another 
process. 

Fine point: If an application is not running in the notifier process and needs to obtain or manipulate the selection, 
a TIP.PeriodicNotify may be used. TIP.CreatePeriodicNotify allows the application to be called back from inside 
the notifier process. 

39.1.2 Essentials for a Requestor 

Clients that need the value of the current selection. 

39.1.2.1 Convert, Target, Value, Enumerate, Can YouCon vert 

The fundamental operation performed by a selection requestor is to obtain the value of the 
current selection by calling Selection.Convert. Convert takes a Selection.Target and returns a 
Selection.Value. The Target specifies what type of data the selection should be converted to. 
The Value contains a pointer to the converted selection. For example, Selection.Convert 
[target: string] will return a pointer to a string, i.e., an xstring. Reader. 

Not all selections can be converted to all Targets; in fact most selections can be converted 
to only a small number of Targets. For example, if the selection is a text string, it can be 
converted to Target string and perhaps to integer, but probably not to file or fileType 
Note: Converting to some Targets is not so much requesting the value of the selection as 
requesting some general information about the selection or its environment. For example,, 
Selection.Convert [target: window] is a request for the window that the selection is in, 
Selection.Convert [target: help] is a request for user help information about the selection, 
etc. Note that Target is an open-ended enumeration and that clients can create new 
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Targets by using Selection. UniqueTarget. The type associated with each Target is 
^llBP^ determined by system-wide convention. Several of these TYPE/Target conventions are 

defined below under the description of Target. Other TYPE/Target conventions are 
documented in §39.2.1.1, Convert. 

A requestor can also enumerate the selection if it is more than a single item or if it can be 
split into smaller pieces. This is done by calling Selection. Enumerate. 

Finally, a requestor can determine what Targets the selection can be converted to without 
actually doing the conversion by calling Selection.CanYouConvert, Selection. Query, or 
Selection.HowHard. 

39.1.2.2 Resource Allocation/Deallocation Considerations 

It is a strict rule that the Values produced by Selection. Convert and Selection. Enumerate 
describe objects owned by the selection manager. The requestor may examine the data 
referenced by the value field, but must not alter it. Furthermore, the requestor must free 
the Value (using Selection. Free) once he no longer needs it. 

If the requestor wishes to (1) keep the value after it returns to the system, or (2) pass the 
value to another process, it must call Selection.Copy, Selection. Move, or Selection.CopyMove. 
These in turn invoke a procedure supplied by the selection manager that modifies the 
Value such that the requestor may then make changes to value f without affecting the 

selection manager. Fine Point: The procedure supplied by the manager is returned by the manager as part of 
the Value record. If a Move is performed, the item is also deleted from the manager's domain. 
^■■^ After the Move or Copy, any storage associated with the Value is now owned by the 

requestor. This storage may be freed by calling Selection. Free. 

For example, if the current selection is a document icon, then Convert[file] yields a Value 
containing a LONG pointer to NSFile. Reference for the file containing the document. If the 
requestor were to create a new document and associate it with the same file, it would 
probably have undesirable effects. Instead, the requestor should call Copy, passing in 
data:L0NG pointer to NSFile. Reference for the destination directory of the new file. When 
Copy returns, the Value contains a reference to a copy of the original file, and the 
requestor can use this freely. 

As a second example, suppose the selection manager uses a Mesa string as the internal 
selection representation. Then Convert[string] simply builds the string pointer into an 
xstring.Reader using xstring.FromSTRING. If the requestor wants to save the string for very 
long, he should call Copy, and the manager will allocate a copy of the original string using 
the zone passed to Convert. An alternative, somewhat simpler, is for the requestor to call 
xstring.CopyReader or xstring.CopyToNewReaderBody or xstring.CopyToNewWriterBody 
to copy the bytes, and then call Selection. Free to dispose of the original Reader. 

39.1.3 Essentials for a Manager 

Clients that own and manage the current selection. 
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39.1.3.1 Set, ConvertProc, ActOnProc, ManagerData 

The implementor of a selection manager needs to know everything that the implementor 
of a selection requestor knows, plus more (see the previous section Essentials for a 
Requestor). 

The fundamental operation performed by a selection manager is to become the current 
manager by calling Selection. Set. Set takes a ConvertProc, an ActOnProc, and a long 
POINTER (ManagerData). 

The ConvertProc is called to obtain the value of the selection, whenever a requestor calls 
Selection.Convert or Selection. Enumerate. The ConvertProc is also called to determine what 
Targets the selection can be converted to, whenever a requestor calls 
Selection.CanYouConvert, Selection. Query, or Selection. HowHard. Conversionlnfo is a variant 
record passed to the ConvertProc that indicates which operation to perform: convert, 
enumeration, or query. 

The ActOnProc is called to perform various Actions on the selection, such as mark, 
unmark, and clear. 

The ManagerData passed to Set is passed back to the ConvertProc and the ActOnProc. 
Typically, the ManagerData identifies exactly what portion of the manager's domain is 
currently selected. For example, if the current selection is some text in a document, the 
actual manager is the document application, which has some ManagerData that indicates 
exactly which characters are currently selected. 

When a manager calls Selection. Set, the previous manager is told to ActOn [clear], and 
Selection forgets about the previous manager. Hence, there is only one selection at a time. 
However, Selection also supports the notion of a "saved" selection. A client can become the 
current manager by calling Selection. SaveAndSet, which does a Set but also saves the 
previous selection. Later, the manager that did the SaveAndSet can do a Selection. Restore, 
which restores the previous selection. 

39.1.3.2 More on Selection. Value, ValueFreeProc, and ValueCopyMoveProc 

The Value produced by a manager's ConvertProc contains more than simply a pointer to 
the converted selection. It also contains a pointer to two procedures, a ValueFreeProc and a 
ValueCopyMoveProc. The ValueFreeProc is called when the requestor calls Selection. Free so 
that the manager can release any resources that were allocated when the selection was 
converted. The manager's ValueCopyMoveProc is called when the requestor calls Copy, 
Move, or Copy Move. The ValueCopyMoveProc should copy or move the converted 
selection value so that the manager no longer owns the resources associated with the 
value. A third field in the Value record is a long unspecified that may be used to store data 
for the ValueFreeProc and the ValueCopyMoveProc. 

If the converted selection value can be copied or moved, the manager must return a 
ValueCopyMoveProc with the Value. For example. Targets string and file can be moved or 
copied, while it does not make sense to move or copy Targets window and filelype. The 
ValueCopyMoveProc modifies the Value such that the requestor may then make changes 
to value 1 without affecting the selection manager. If a Move is performed, the item is 
also deleted from the manager's domain. (Some managers may implement Copy but raise 
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Error[mvalidOperation] if asked to do a Move.) The interpretation of the data given to a 
^m*^ ValueCopyMoveProc depends on the manager; the typical use is to specify a destination 

for the object. 

39.1.3.3 Storage Considerations for ConvertProc 

As stated above, it is a strict rule that the Values produced by the ConvertProc describe 
objects owned by the manager. If the manager allocated any resources to produce the 
converted selection value, then a ValueFreeProc must be returned with the Value so that 
the resources can be released. If a ValueCopyMoveProc was returned with the Value, after 
the converted selection value has been copied or moved, the manager must ensure that the 
correct things will happen when the Value's ValueFreeProc is called (i.e., when the 
requestor calls Selection. Free). This may involve replacing the original ValueFreeProc. 

The manager's ConvertProc takes a zone that Selection guarantees is valid (except for the 
query operation). The manager should allocate any storage for the converted selection 
value from that zone. The ConvertProc can store the zone in the context (long unspecified) 
field of the Value record (or in a record pointed to by the context field). The ValueFreeProc 
and ValueCopyMoveProc can then retrieve this zone to free the storage. 

Numerous defaults are provided by Selection to ease the manager's task of proper storage 
management. In practice, the ConvertProc can simply default the context field and 
Selection will place the zone there. Also, procedures such as FreeStd and FreeContext are 
provided that perform the loopholes, free the storage, and store null and/or no-op values 
- J such as NopFree in the Value record. 

39.1.3.4 Storage Considerations for ManagerData 

The ManagerData that identifies exactly what part of the manager's domain is currently 
selected should be allocated whenever a Selection. Set is done and deallocated whenever 
ActOn [clear] is requested. In particular, a manager should not assume that there will be 
only one selection at a time in his domain. The existence of SaveAndSet and Restore 
implies that the same manager code could have several pushed selections at once and 
therefore would have several ManagerData records allocated at once. 

39.2 Interface Items 

39.2.1 Requestor items 



39.2.1.1 Convert 

Convert: procedure [target: Target, zone: uncounted zone nil] 
RETURNS [value: Value]; 

Value: type a record [value: long pointer, . . .]; 

nullValue: Value a [value: nil,. . .]; 
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Convert is a request to the current selection manager to produce the selection as a type 
specified by target, if possible, value. value will be a long pointer to the converted 
selection. The type of object pointed to by value. value depends on target and is described 
below under Target. If the conversion requires that storage be allocated, it will be 
allocated out of zone. If zone is defaulted, the system heap is used. 

The value returned is read-only; it belongs to the manager. If the requestor wishes to (1) 
keep the value after it returns to the system, or (2) pass the value to another process, it 
must call Copy, Move, or CopyMove to make a copy of the value, which is then owned by 
the requestor. If Copy, Move, or CopyMove is called, the requestor must still call Free. 

If Copy, Move, or CopyMove is not called, the requestor must call Free after calling 
Convert. This allows the manager to free any resources that were allocated to perform the 
conversion. If Copy, Move, or CopyMove is called, the requestor then owns any resources 
and may retain them indefinitely and/or may free them by calling Free. 

There are other fields in the Value record, but the requestor need not be concerned with 
them. They are described in the section on Manager Items 

nul lvalue is returned if the selection manager does not implement the desired conversion, 
or if the particular selection is incompatible with the target (e.g., Convert[integerl when 
non-numeric characters are selected). 

Target: type = machine dependent{ 

v\/inclow(0), shell, subwindow, string, length, position, 
integer, interpressMaster, file, fileType, token, help, 

interscriptScript, interscriptFragment, serializedFile, name, firstFree, last(1777B)}; 

Target describes the type of data to which a selection may be converted (see Convert). 
Modules that manage the current selection may choose not to implement conversion to 
some (or even most) of these types. The values described below are those stored in the 
value field of the Selection. Value returned by Convert. 

Special note for Targets that produce a stream. Handle: The stream. Object pointed to by the 
Stream. Handle is read-only. Thus the requestor cannot even read the stream because that 
alters the stream state and thus the Stream. Object. Before using the stream, the requestor 
must do a Copy, after which the ownership of the storage for the Stream. Object and any of 
its ancillary data moves to the requestor. Note also that the stream itself is read-only even 
after the Copy. The requestor should never attempt to write to the stream. After reading 
the stream, the requestor can free the stream and any associated resources by calling 
Stream. Delete. Thus a typical stream requestor will do Convert[stream]; CopyH; <read 
stream >; stream. Deleted; Note for selection managers: this last point means that the 
Stream. Delete must be able to free any ancillary data associated with the stream. 

Note that some Target values refer to types that are not defined within the context of 
ViewPoint. Such targets so far include pieceList, help, interscriptScript, and 
interscriptFragment. Popular target types are included in the Selection interface as a 
convenience for clients. New target types will be put either into a Selection Extras 
interface or, for little-used types, into private interfaces negotiated between managers and 
requestors and using Selection. UniqueTarget. The TYPE associated with each Target is 
determined by system-wide convention. Several of these TYPE/Target conventions are 
defined here. Other TYPE/Target conventions are documented elsewhere, see §39.2.2.8, 
UniqueTarget. 
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Fine Point: This Selectioin interface is intended to support both Tajo and ViewPoint clients, so there may be 
Targets that do not make sense in one domain or the other. Targets that only make sense in one domain show that 
domain in parentheses. 



window 
shell 



yields a window. Handle for the window containing the selection. 

yields a StarWIndowSheJI. Handle for the window containing the 
selection. (Star) 



subwindow 



string 



length 



yields a Window. Handle for the subwindow containing the 
selection. (Tajo) 

yields a LONG POINTER TO xstring.ReaderBody (an xstring.Reader) 

representing the text of the selection. If the current selection is 
too large, the manager of the selection may return nullValue 
when asked to convert to a string. The requestor should then ask 
to enumerate the selection as a sequence of smaller strings. Note: 
The requestor must copy the ReaderBody before altering it. 

yields a long pointer to long cardinal containing the length of the 
selection in characters. 



position 



yields a LONG POINTER TO long cardinal containing the position 
within the source. 



pieceList 



integer 



interpressMaster 



file 



fileType 



yields a list of pieces, understood by the internals of Tajo's 
PieceSource interface. (Tajo) 

yields a LONG pointer TO long integer containing the result of 
converting the contents of the selection to a number. 

yields a Stream. Handle onto an Interpress master, according to the 
Interpress standard. 

yields a long pointer to NSFile.Reference for the file (if any) 
associated with the selection, e.g., the backing file for a Star 
document icon. When calling Copy, Move, or CopyMove, the 
data parameter must be a long pointer to NSFile.Reference of the 
parent directory to where the file should be copied or moved. (Star) 

yields a long pointer to NSFile.Type for the file (if any) associated 
with the selection. (Star) 



token 



help 



yields a long pointer to xstring.ReaderBody (an xstring.Reader) 

that contains the first token of the current selection. Note: The 
requestor must copy the ReaderBody before altering it. 

yields a LONG POINTER to a value or data structure that specifies 
what should happen if the help key is pressed. Consult the Help 
documentation (not in this manual) for the exact type. 
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interscriptScript yields a stream. Handle onto a complete script, according to the 
Interscript standard. It begins with the "Interscript 1.0 . . and 
is in machine code. 

interscrlptFragment yields a stream. Handle onto a single Interscript node, in machine 
code. 



serializedFlle A Target of serializedFile results in a stream. Handle. 

Stream. GetXXX operations can be performed on the stream. This is 
useful for retrieving files from non-NSFile mediums such as a 
floppy disk. 



name 



A Target of name results in a xstring. Reader that contains the 
name of the object. 



firstFree 



is used internally by UniqueTarget and should not be used by 
clients. 



ConvertNumber: procedure [target: Target] 

RETURNS [ok: BOOLEAN, number: long unspecified!; 



This procedure lets the requestor streamline his code in many cases. ConvertNumber calls 
Convert and assumes that the resulting value. value references a 32-bit object. (This is 
true of the targets length, position, integer, and fileType, and may also be true of targets 
defined using UniqueTarget.) The object is returned as number, and the Value is then 
freed (Selection. Free). If the selection manager does not support the desired conversion (that 
is, it returns null Value), or if the selection could not be converted to a number, 
ConvertNumber returns ok:FALSE; otherwise, it returns ok:TRUE. 



Free: procedure [v: ValueHandlej; 
ValueHandle: TYPE 3 long pointer to Value; 



Free frees any storage associated with v. If the requestor has not done a Copy, Move, or 
CopyMove, that storage is owned by the manager. After doing a Copy, Move, or 
CopyMove, that storage is owned by the requestor. 



39.2.1.2 Query 

A requestor can determine exactly which Targets the current selection can be converted to 
and how difficult the conversion would be. The most common way to do this is 
CanYouConvert, which takes a Target and returns a boolean indicating whether the 
selection can be converted to that Target. HowHard is similar to CanYouConvert but 
returns a Difficulty. Query allows a requestor to determine the Difficulty of conversion for 
an ARRAY of Targets. 



Note: For all these queries, the manager is indicating how hard it would be to attempt to 
convert the selection to that target type. Attempt is a key word. The manager might be 
willing to attempt to convert the selection to an Interpress master and yet run out of disk 
space when the conversion is actually requested. Likewise, the manager might support 
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conversion to integer, but the conversion could still fail if the selection contains invalid 
characters. 

CanYouConvert: procedure [target: Target, enumeration: boolean ^ false] 
RETURNS [yes: boolean] = inline { 

RETURN [ HowHard [ target, enumeration ] # impossible ] }; 

CanYouConvert determines whether the selection manager supports conversions to the 
specified target, enumeration = true means the requestor wants to know if the manager 
supports enumerating the selection in the specified target form. (See the section on 
Enumeration below.) 

HowHard: procedure [target: Target, enumeration: boolean «- false] 
RETURNS [difficulty: Difficulty]; 

Difficulty: type = {easy, moderate, hard. Impossible}; 

HowHard determines the difficulty the selection manager would have attempting to 
convert to the specified target, enumeration = true means the requestor wants to know 
the difficulty of enumerating the selection in the specified target form. (See the section on 
Enumeration below.) 

The difficulty ratings are interpreted roughly as follows: 

easy Requires virtually no computation (other than allocating 

storage for the Value). Example: length when the selection is 
^tm^' being maintained as two character indices within a string. 

moderate Requires some amount of computation but nothing outrageously 
time-consuming. Example: converting the above-mentioned 
substring representation to a string or integer target. 

hard Requires extensive computation. Example: interpressMaster. 

impossible The selection manager does not support this conversion. 

Query: procedure [targets: long descriptor for array OFQueryEIement]; 

QueryElement: type ■ record [ 
target: Target, 

enumeration: boolean <- false, 
difficulty: Difficulty <- trash]; 

Query allows a requestor to determine the difficulty of conversion for several Targets. The 
requestor should construct the array of QueryElement, filling in target and enumeration 
for each QueryElement. The manager will then store a Difficulty in each QueryElement 
indicating how hard it would be to attempt to convert the selection to that target. The 
requestor can then examine the difficulty field of each QueryElement after the call to 
Query. 

39.2.1.3 Enumeration 

The selection is sometimes a collection of items (for example, several rows of a folder) or a 
single large item that can be split up (for example, a long string can be broken into several 
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smaller ones). A requestor can request that each item or part of such selections be 
converted to some Target by calling Selection. Enumerate. Enumerate is logically similar to 
calling Convert for each item and the same storage ownership rules apply (see Convert). 
Not all selection managers support enumerating the selection; for example, they do not 
support a selection that is more than one item. Often a requestor will call Convert and if 
that fails (returns nullValue), call Enumerate. 

Enumerate: procedure [ 

proc: EnumerationProc, target: Target, data: RequestorData «-nil, 
zone: uncounted zone <- nil] 
RETURNS [aborted: boolean]; 

EnumerationProc: type = procedure [element: Value, data: RequestorOata] 

RETURNS [stop: BOOLEAN «- FALSE]; 

RequestorOata: TYPE ■ long pointer; 

Enumerate is a request to the selection manager to enumerate the current selection, 
converting each element to target, proc is called for each element, data is passed back to 
proc each time it is called. As with the Value returned by Convert, the requestor must 
consider each element to be read-only until Copy, Move, or CopyMove is called, and the 
requestor may free the value by calling Free. 

stop is returned from proc by the requestor and indicates whether the enumeration should 
be stopped, aborted indicates whether the enumeration completed normally or terminated 
prematurely. 

If the manager cannot convert the selection to the target type or if the manager does not 
implement enumeration, proc will not be called. 

Reconversion: signal [ 

target: Target, zone: uncounted zone] returns [Value]; 

ReconvertDuringEnumerate: procedure [ 

target: Target, zone: uncounted zone <- nil] returns [Value]; 

A requestor may wish to reconvert the current item during an enumeration of the 
selection. The requestor should call ReconvertDuringEnumerate, which will raise the 
signal Reconversion. If the manager supports reconversion, it should catch the signal and 
return the reconverted value. If the manager does not support reconversion, it should 
ignore the signal. Enumerate will catch the signal and return nullValue. 
ReconvertDuringEnumerate acts like Convert with respect to zone. 

maxStringLength: CARDINAL a 200; 

maxStringLength is the largest string that is produced by a Convert[string]. Further, a 
manager that supports target: string should be prepared to yield strings up to this length, 
and should never yield a string longer than this. Thus the requestor knows that (1) 
Convert[stringl will never produce too large a string, and (2) if Convert[string] fails but 
the selection manager claims to support conversion to strings, the selection must be rather 
long (and thus might be deemed uninteresting without further examination). If the 
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requestor wants the selection as a string regardless of its length, he should use 
Enumerate. 

39.2.1.4 Copy, Move, Free, etc. 

The Values produced by Convert and Enumerate are strictly read-only. The storage is 
owned by the manager. The requestor may examine the data referenced by the value field 
but must not alter it. 

If the requestor wishes to (1) keep the value past when it returns to the system, or (2) pass 
the value to another process, it must call Copy, Move, or CopyMove. These in turn invoke 
a procedure supplied by the selection manager that modifies the Value such that the 
requestor may then make changes to value. value 1 without affecting the selection 

manager. Fine Point: This procedure is returned by the manager as part of the Value record, but the requestor 

neverneedsto know about these details. If a Move is performed, the item is also deleted from the 
manager's domain. After the Move or Copy, any storage associated with the Value is now 
owned by the requestor. This storage may be freed by calling Free. 

For example, if the current selection is a document icon, then Convert[file] yields a Value 
containing a LONG POINTER TO NSFile. Reference for the file containing the document. If the 
requestor were to create a new document and associate it with the same file, it would 
probably have undesirable effects. Instead, the requestor should call Copy, giving it a long 
POINTER TO NSFile.Reference for the destination directory of the new file. When Copy 
returns, the Value contains a reference to a copy of the original file, and the requestor can 
use this freely. Furthermore, whereas calling Free with the original Value might have 
deleted the file (since the file then belonged to the manager, who might have created it 
solely for the Convert request), calling Free for the new Value frees only the 
NSFile.Reference storage (since the file is now a permanent object belonging to the 
requestor). 

Copy: PROCEDURE [v: ValueHandle, data: long pointer] = inline { 
CopyMovefv, copy, data]}; 

Move: procedure [v: ValueHandle, data: long pointer] = inline { 
CopyMove[v, move, data]}; 

CopyMove: ValueCopyMoveProc; 

ValueCopyMoveProc: type a procedure [ 

v: ValueHandle, op: CopyOrMove, data: long pointer]; 

CopyOrMove: type a {copy, move}; 

Copy, Move, and CopyMove request the manager to make a copy of the converted 
selection value (v. value f ) and, for Move, also delete the selection from the manager's 
domain. A requestor may call these procedures after calling Convert or from an 
EnumerationProc while doing an Enumerate, data will be passed to the manager; what it 
points to depends on the particular Target, data often points to a destination container for 
the copied value. For example, for Target file, data is a long pointer to NSFile.Reference for 
the destination directory. The exact meaning of data for each target is specified in the 
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description of that target under Target above. Copy, Move, and CopyMove may raise 
Error [invalidOperation]. 

39.2o2 Manager Items 

39,2.2.1 Set 

Set: PROCEDURE [pointer: ManagerData, conversion: ConvertProc, actOn: ActOnProc]; 
ManagerOata: TYPE a longpointer; 

The Set procedure allows a client to become the manager of the current selection by 
supplying the Selection interface with a pair of procedures. The ActOnProc is called to 
modify or manipulate the current selection. The ConvertProc is called to get the value of 
the current selection. The value of pointer passed to Set is used as the data argument in 
calls to conversion or actOn. pointer typically points to a record that describes what part 
of the manager's domain is currently selected. If there is already a selection manager 
when Set is called, Set first calls that manager with ActOn[unmark] and ActOn[ciear]. Set 
automatically calls the new ActOnProc with an action of mark. 

Either conversion or actOn can be explicitly nil. If conversion is nil, then Convert always 
returns nullValue, Enumerate is a no-op, and Query will always respond impossible. If 
actOn is NIL, then ActOn is a a no-op for all actions. 

ConvertProc: type ■ procedure [ 
data: ManagerData, 
target: Target, 
zone: uncounted zone, 
info: Conversionlnfo «- [convert[]] ] 
returns [value: Value]; 

Conversionlnfo: TYPE ■ record [select type: *from 
convert = > null, 

enumeration s > [proc: procedure [Value] returns [stop: boolean]], 
query = > [query: long descriptor for array of QueryElement], 
endcase]; 

A ConvertProc is provided by a manager when becoming the manager; that is, when 
calling Set or SaveAndSet. The manager's ConvertProc is called when a requestor calls 
Convert, Enumerate, or Query. The ConvertProc should perform the conversion, the 
enumeration, or the query, info is a variant record indicating which operation to perform; 
it contains data appropriate to each operation. The ConvertProc should use with info 
select to determine which operation is requested. Each operation is described in detail in 
the following sections, data is the pointer that was passed to Set or SaveAndSet and 
typically points to a record that describes what part of the manager's domain is currently 
selected, target indicates the type of object that the selection should be converted to and is 
meaningful only for conversion and enumeration, zone should be used to allocate any 
storage for the converted selection value and is meaningful only for conversion and 
enumeration. 
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. ActOnProc: type = procedure [data: ManagerOata, action: Action] 

^■P*^ RETURNS [cleared: boolean <- false]; 

An ActOnProc is provided by the manager of the selection to perform various actions on 
the selection. ActOnProc is fully described later in this chapter. 

39.2.2.2 Conversion 

Conversionlnfo: TYPE = record [select type: * from 
convert a > null, 

endcase]; 

Value: type a record [ 
value: LONG pointer, 
ops: LONG pointer TO ValueProcs*-NiL, 
context: long unspecified «-0]; 

Convert calls the manager's ConvertProc with convert Conversionlnfo to perform the 
requested conversion. The ConvertProc returns a value: Value. If the conversion can be 
performed, value. value should point to the converted selection value; value. ops should 
point to a pair of procedures, a ValueFreeProc that will release any resources that were 
allocated to perform the conversion and a ValueCopyMoveProc that will copy or move the 
converted value; value. context can be used to save any information that the pair of 
procedures might need, value. ops and value.context are described in much more detail 
later. If the manager does not support the requested Target or there is some problem with 
the conversion, the ConvertProc should return nullValue. See Target for the effect of 
different conversion targets. 

If the conversion requires that an object be allocated, the ConvertProc should allocate it 
out of zone. If the requestor passed a nil zone to Convert, Convert passes the system zone 
to ConvertProc. The ConvertProc can assume that it is always given a valid zone. 

39.2.2.3 Query 

Conversionlnfo: type = record [select type: * from 

query = > [query: longdescriptorfor array of QueryElement], 
endcase]; 

QueryElement: type = record [ 
target: Target, 

enumeration: boolean <- false, 
difficulty: Difficulty *- trash]; 

Query, HowHard, and CanYouConvert call the manager's ConvertProc with query 
Conversionlnfo. The ConvertProc should examine the target and enumeration fields of 
each QueryElement (these were filled in by the requestor) and fill in the difficulty field 
indicating how hard it would be to attempt to convert the selection to that target 
(enumeration = false) or to convert the selection to an enumeration of that target 
(enumeration « true). 
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All managers are expected to implement queries; the assumption is that most difficulty 
ratings can be determined simply by indexing into a constant array. The Value actually j 
returned by the ConvertProc in response to a query is ignored; nullValue or trash may be 
returned. 



Note that the manager is indicating how hard it would be to attempt to convert the 
selection to that target type. Attempt is a key word. The manager might be willing to 
attempt to convert the selection to an Interpress master, and yet run out of disk space 
when the conversion is actually requested. Likewise, the manager might support 
conversion to integer, but the conversion could still fail if the selection contains invalid 
characters. 

39.2.2.4 Enumeration 

Conversionlnfo: type = record [select type: *from 

» • • * 

enumeration s > [proc: procedure [Value] returns [stop: boolean]], 

" • ■ # 

endcase]; 

Enumerate calls the manager's ConvertProc with enumeration Conversionlnfo. The 
ConvertProc should convert each element or part of the selection according to target and 
call proc for each element. The Value passed to proc is just as it is for conversion (see the 
section on Conversion above and the following section). If proc returns stop ■ true, the 
•ConvertProc should stop the enumeration and return. The Value returned by the 
ConvertProc after an enumeration is ignored; nullValue or trash may be returned. Not all 
selection owners are expected to implement enumerations; if an enumeration is requested 
and not supported, the ConvertProc should simply return and take no other action. Fine 

Point: The ConvertProc does not call the requestor's EnumerationProc directly; rather, proc is inside Enumerate 
and Enumerate calls the requestor's EnumerationProc. This lets Enumerate insert the zone into the 
Value.context if it is zero, just as Convert does for Values produced by a simple conversion. 



maxStringLength: cardinal = 200; 



maxStringLength is the largest string that should be produced by a ConvertProc. Further, 
a ConvertProc that supports target: string should be prepared to yield strings up to this 
length, and should never yield a string longer than this. Thus the requestor knows that (1) 
Convert[string] will never produce too large a string, and (2) if Convert[string] fails but 
the selection manager claims to support conversion to strings, the selection must be rather 
long (and thus might be deemed uninteresting without further examination). 



39.2.2.5 Free, Copy, Move, etc. 

ValueHandle: TYPE = long pointer to Value; 

Value: type = record [ 
value: long pointer, 
ops : long pointer to Va I ueProcs <- nil, 
context: long unspecified 0] ; 
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The selection manager provides the value of the selection, or other selection-related 
information, to the requestor by means of Value records. These records are typically either 
returned by a ConvertProc or passed as elements to the requestor's EnumerationProc. The 
ops field defines the effect of Free, Copy, Move, and CopyMove. The context field may be 
used to store data for use by the ops procedures. If the context field is defaulted (zero) by 
the selection manager, Selection stores the zone that was passed to the ConvertProc there 
before the Value is handed to the requestor. 

ValueProcs: type a record [ 
free: ValueFreeProc<-NiL, 
copyMove: ValueCopyMoveProc <- nil]; 

ValueProcs are returned by the manager as part of a Value record. If the manager 
allocated any resources to produce the converted selection value, then a ValueFreeProc 
must be returned with the Value so that the resources can be released, free is called when 
the requestor calls Free. If the converted selection value can be copied or moved, the 
manager must return a ValueCopyMoveProc with the Value. For example. Targets string 
and file can be moved or copied, while it does not make sense to move or copy Targets 
window and fileType. copyMove will be called when the requestor calls Copy, Move, or 
CopyMove. 



39.2.2.5.1 Free 



ValueFreeProc: TYPE a procedure [v: ValueHandle]; 

If any resources were allocated to produce the converted selection value, they should be 
released in the manager's ValueFreeProc. The ValueFreeProc is returned as part of the ops 
field of a Value. The ValueFreeProc will be called when the requestor calls Free, v points to 
the Value that represents the converted selection. 

Defaults are provided such that for the most common case when the ConvertProc simply 
allocates one node of storage from the passed zone, the manager need not supply a 
ValueFreeProc. Selection takes care of freeing the storage when the requestor calls Free. 
The details of how this works are as follows: 

The manager's ConvertProc takes a zone that Selection guarantees is valid. The manager 
should allocate any storage for the converted selection value from that zone. The 
ConvertProc can store the zone in the context field of the Value record (or in a record 
pointed to by the context field); then the ValueFreeProc can retrieve this zone to free the 
storage. Selection stores this zone in the context field if context is zero (the default) in the 
Value returned by the ConvertProc (or passed to the EnumerationProc). v. value points at 
the converted selection object to be freed. Now, Free calls FreeStd if the Value passed to 
Free has ops = nil or ops.free = nil. FreeStd treats v.context as a zone and calls 
v.context.FREE[@v. value]. 

If there are in fact no resources that should be freed (for example, after Convert(window]), 
the selection manager should use NopFree as the ValueFreeProc. (See also 
nopFreeValueProcs.) 



39-15 



39 



Selection 



FreeStd: ValueFreeProc; 

FreeStd assumes the resources of the Value can be freed by treating v.context as a zone 
and calling v.context.FREE[@v.value]. If a Value has ops = nil or ops.free = nil. Free will 
call FreeStd. 

NopFree: ValueFreeProc; 

The NopFree procedure should be used as the ops.free for a Value involving no temporary 
resources owned by the selection manager. Thus, a Value created by Convert[window] 
would probably use NopFree, as would Convert[string] if the Value. value pointed to a 
permanent xstring.ReaderBody belonging to the manager. (See also nopFreeValueProcs.) 

39.2.2.5.2 Copy and Move 

ValueCopyMoveProc: type = procedure [ 

v: VaiueHandle, op: CopyOrMove, data: long pointer]; 

CopyOrMove: type = {copy, move}; 

The manager's ValueCopyMoveProc is called to copy or move the converted selection 
value. A ValueCopyMoveProc is returned by the manager's ConvertProc as part of the ops 
field of a Value. The ValueCopyMoveProc is called when the requestor calls Copy, Move, 
or CopyMove. The ValueCopyMoveProc should modify the Value such that it no longer 
involves any manager-owned storage. If a Move is performed, the item is also deleted from 
the manager's domain. (Some managers may implement Copy but raise 
ErrorfinvalidOperationl if asked to do a Move.) data is the data parameter that the 
requestor passed to copy or move. It is often a pointer to the destination container for the 
copied value. The interpretation of data depends on the Target; it is specified in the 
description of each target under Target above, v points to the Value representing the 
converted selection, op indicates whether to do a copy or move. Note: v.context can be 
used by the manager to save information between the ConvertProc and the 
ValueCopyMoveProc. 

The ValueCopyMoveProc should release (or perhaps simply turn over control of) any 
resources that were allocated by the ConvertProc to produce the original converted value. 
Conceptually, the ValueCopyMoveProc makes a copy of the converted value, then releases 
any resources that were used to produce the original converted value. If the original 
converted value itself was a copy produced by the conversion process, this effect might be 
achieved by doing nothing -- the requestor just becomes the owner of the copy. 

If the converted value can only be copied once (the typical case), the ValueCopyMoveProc 
should also set v.ops.copyMove to nil to prevent the manager's ValueCopyMoveProc from 
being called again. If the requestor does call Copy or Move again, Selection raises Error 
[invalidOperation]. 

The ValueCopyMoveProc should also ensure that v. ops.free and v.context have 
appropriate values so that when the requestor calls Free, the right thing happens. For 
example, if the newly copied selection was allocated from a zone, v.ops.f ree should free it 
from that zone (see ValueFreeProc and FreeStd); or if the newly copied selection has no 
storage allocated for it, v. ops.free should be NopFree. 
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nopFreeValueProcs: readonly long pointer to ValueProcs; @[NopFree, nil] 

This is provided for use as the ops vector in Values that require no temporary storage and 
that cannot be moved or copied. The window and subwindow Targets typically produce 
such values. 

FreeContext: procedure [v: ValueHandle, zone: uncounted zone] s inline ( 
zone.FREE(LOOPHOLE[@v.context, LONG pointer to long pointer]] ; 
v.context <~LOOPHOLE(zone]}; 

When the requestor calls Copy or Move, the manager's ValueCopyMoveProc is expected 
to modify the Value that it no longer involves any manager-owned storage. If the manager 
has been using the context field as a pointer to additional private data, this private data 
must be freed. This would normally require merely a zone.FREE[@v. context]; however, 
since the context is a LONG unspecified, a loophole is needed. FreeContext hides this 
LOOPHOLE from the implementor and does the required zone. free. It also stores the zone in 
place of V. context, for possible later use by FreeStd. 



39.2.2.6 ActOn 



ActOnProc: type = procedure [data: ManagerOata, action: Action] 
returns [cleared: boolean <- false]; 



An ActOnProc is provided by the manager of the selection to perform various actions on 
the selection, data is the pointer that was passed to Set or SaveAndSet and typically points 
to a record that describes what part of the manager's domain is currently selected, action 
indicates what action to perform (see Action below). An ActOnProc should return cleared: 
true if the action resulted in the selection being cleared; that is, the manager is no longer 
responsible for the selection. (This should always be the case for action: clear and may also 
occur for delete or clearlfHaslnsert.) 

Action: type a machine dependent{ 

clear(O), mark, unmark, delete, clearlfHaslnsert, save, restore, firstFree, last(255)}; 



clear unselects the current selection by freeing any associated 

private data, undoing TIP notification changes, etc. 

mark highlights the current selection. If the selection is already 

highlighted, this is a no-op. 

unmark dehighlights the current selection. If the selection is not 

already highlighted, this is a no-op. 

delete deletes the contents of the current selection. The selection 

manager may decide against actually deleting it. 



clearlfHaslnsert same as unmark plus clear, but only if the insertion point 
(input focus) is in the selection. This action is used when a 
secondary selection has been completed (for copy-from); if the 
place to which the secondary selection is to be copied (the 
insertion point) is within the selection itself, the selection is 



39-17 



39 



Selection 



cleared after obtaining its contents and before the insertion 
takes place. 



save 



unselects the current selection, but does not necessarily free 
any associated private data, because the selection is expected 
to be restored later. This action will often be a no-op, but the 
manager might need to undo a special TIP notifier, for example. 



restore 



restores a previously saved selection. 



firstFree 



is used internally by UniqueAction and should not be used by 
clients. 



Observe that, contrary to the interpretations used in the XDE Selection interface, the 
clear action does not dehighlight the selection. Selection.Ciear (usually) does an explicit 
unmark before clearing the selection. Likewise, save does not imply unmark, nor does 
restore imply mark. This lets a client choose to leave a primary selection highlighted 
while a secondary selection is being made. 



39.2.2.7 Save and Restore 

SaveAndSet: procedure [ 

pointer: ManagerData, conversion: ConvertProc, actOn: ActOnProc, 
unmark: boolean 4-true] 
RETURNS [old: Saved]; 

SaveAndSet is the same as Selection. Set except that the existing selection, if any, is told to 
ActOn[savel rather than ActOnfclear]. That is, the existing selection is expected to retain 
any private state so that it can later be restored via Selection. Restore. If it subsequently 
turns out that the saved selection is never going to be restored, it should be given to 
Selection. Discard so that the former selection manager will have a chance to discard any 
associated private data. A saved selection must always be given eventually to either 
Restore or Discard; furthermore, once that has been done, the Selection. Saved must not be 
used for anything else. 

It is perfectly acceptable to call SaveAndSet when there is no selection. If the resulting 
Selection. Saved is passed to Selectlon.Restore, it acts like Selection.Ciear. Also, unlike for 
Clear, ClearOnMatch, and Restore, it is quite reasonable to call SaveAndSet with unmark: 
FALSE, thereby requesting that the saved selection remain highlighted while a secondary 
selection is performed. If this is done, the caller will usually wish to specify mark: false 
when the saved selection is restored. Note: Calling SaveAndSet with unmark: false does 
not necessarily mean that the old selection is marked. The selection manager, or some 
other client, might have unmarked it. The present caller is simply saying, "Do not change 
the highlighting on my account," but has no way of knowing whether the saved selection is 
in fact highlighted. That is why it is always up to the selection manager to decide whether 
ActOn[mark] or ActOn[unmark] is a no-op. 

Saved: type [61; 

Objects of this type are created by Selection. SaveAndSet to encapsulate a selection that is to 
be restored later. It is opaque to prevent requestors from invoking the manager directly. 
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Restore: procedure [saved: Saved, mark, unmark: boolean <-true]; 

This procedure re-institutes a previously saved selection as the current manager. The 
existing selection, if any, is requested to ActOn [unmark] (unless unmark is false; see 
Selection. CI ear) and then ActOn[clear]. The selection being restored is asked to 
ActOn[restore] and then ActOn[mark] (unless mark is false). 

Discard: procedure [saved: Saved, unmark: boolean <-true]; 

If a client, having saved somebody else's selection (see SaveAndSet), determines that it 
should never be restored, he should call this procedure to free the associated resources. 
The current selection is not affected. The ActOnProc of the saved selection is called with 
action: unmark (unless unmark is false; see Clear) and again with action: clear. Thus the 
ActOnProc must be prepared to handle these operations while the corresponding selection 
is saved. 



39.2.2.8 Miscellaneous 



On all of the procedures below, use unmark: false only if you know the area of the screen 
containing the selection is going to be repainted soon anyway; for example, if the window 
is going away. 

Clear: procedure [unmark: boolean <-true]; 

The Clear procedure requests that the current selection be cleared. It is equivalent to 
calling ActOn[clear], preceded by ActOn[unmark] if unmark is true. The only time unmark 
should be false is if the caller knows the area of the screen containing the selection is 
going to be repainted soon anyway; for example, if the window containing the selection is 
going away. 

ClearOnMatch: procedure [pointer: ManagerData, unmark: boolean 4-true]; 

It is sometimes difficult to determine if you are the manager of the current selection. The 
ClearOnMatch procedure is the same as Clear except that no action is taken unless pointer 
matches the ManagerData of the current selection. ClearOnMatch is equivalent to if 
Selection. Match[pointer] then Seiection.Clear[unmark]. 



ActOn: procedure [action: Action]; 



The ActOn procedure communicates a request for an action to the manager of the current 
selection. (See also UniqueAction.) Calling ActOn[clear] is not recommended, since there 
would be a tendency to forget to unmark first. Use Selection. Clear instead. 

Match: procedure [pointer: ManagerData] returns [match: boolean]; 

This procedure returns true if the caller is the current selection manager, which is 
assumed to be the case if and only if pointer is equal to the ManagerData associated with 
the current selection (as specified by Set, SaveAndSet, or Restore). Note: A selection 
manager may opt to have nil as the ManagerData. In this cas^e, the manager should not 
use Match since it would not be able to distinguish itself from other managers using nil. 



39-19 



39 



Selection 



However, Match[NiL] always returns false if there is no selection; that is, after 
Selection.Ciear. 



UniqueTarget: procedure returns [Target]; 



The UniqueTarget procedure allows a client to define its own private conversion type. It 
returns a new Target in [firstFree.Jast]. May raise Error [tooManyTargets]. The use of 
private target types severely limits the exchange of information between applications and 
should be avoided if possible. 



UniqueAction: procedure returns [Action] ; 



The UniqueAction procedure allows an application to define its own private operations on 
the selection. It returns a new Action in [firstFree..last]. May raise Error 
[tooManyActions]. 



39.2.3 Errors 



Error: error [code: ErrorCode]; 



ErrorCode: TYPE * { 

tooManyActions, tooManyTargets, invalidOperation. 
operationFailed, didntAbort. didntClear}; 



tooManyActions 
tooManyTargets 
invalidOperation 

operationFailed 



may be raised by UniqueAction. 
may be raised by UniqueTarget. 

raised if Copy or Move is called with a Value that does not 
implement the operation. 

may be raised by a ValueCopyMoveProc if the operation is 
permitted but nevertheless fails, for example due to an NSFile 
error. 



didntAbort and didntClear are never raised. 



39.3 Usage/Examples 



39.3.1 What Selection Is NOT 



The trash bin and insertion features of the Mesa interface are not supported. If they are 
needed, a separate (smaller) interface should be created for them, as they do not really 
require the generality available for actual selections. 

The Selection interface could, in theory, be extended to keep track of objects other than the 
current selection. A parameter could be added to Set, Convert, Enumerate, etc., that would 
describe the data object to be manipulated; the default would be the highlighted selection. 
Thus general information handles could be passed among modules, allowing one module 
to access another's data in whatever target format is most convenient. If there is sufficient 
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demand for such a facility, it may be added someday. (It would probably call for a more 
suitable name than "Selection". Perhaps "Opaque Data"?) 

39.3.2 Random Details 

Requestors need to understand one slightly tricky concept: if they want the selection as a 
String and are prepared to handle very large strings, they should also be prepared to get 
the selection as an enumeration of strings if the selection is longer than 
Selection.maxStrlngLength. (The XDE selection. Source mechanism has been eliminated.) 

39.3.3 Examples of Storage Allocation for Manager's ConvertProc 

Here the various storage allocation cases are discussed that arise, depending on Target, 
how the selection is maintained by the manager, etc. 

• Simplest case: no storage associated with this Target, no copy/move. 

• Example: selection is a string in a window and Target = window. 

• Manager's ConvertProc should have: 

RETURN [ [value: window, ops: Selection. nopFreeValueProcs] ] 

There is nothing allocated, nothing to free, so ops.f ree is Selection. NopFree. It makes no 
sense to copy or move a window this way, so ops.copyMove is nil. 

• Slightly more complex case: no storage associated with this Target, allow copy/move. 

• Example: selection is a piece of a larger backing string and is maintained as an 
xstring.ReaderBody and Target = string. 

• Manager's global frame: 

myVaiueProcs: Selection. ValueProcs [ 

free: Selection. NopFree, copy Move: CopyMoveString ]; 
SelectionData: TYPE = record [ substring: xstring.ReaderBody,... ]; 

— substring points at the same bytes as the backing string 

• Manager's ConvertProc: 

OPEN SelectionData: narrow [data, long pointer to SelectionData]; 
RETURN [ [value: (SselectionData.substring, ops: (@my ValueProcs] ]; 

— Selection will put zone into the context field. 

Here the requestor points directly at the SelectionData. substring. The value. value | 
cannot be changed by the requestor until after the CopyMoveString is called. 

• Manager's CopyMoveString: 
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v.value <- xstring.CopyReader [r: narrow [v.value, xstring.Reader], 

z: NARROW [v.context, uncounted zone] ]; I 
v.ops.free «-nil; 

After doing the copy, v.ops.free is replaced with nil, which causes Free to call FreeStd, 
which frees the copied ReaderBody and bytes. Note: CopyReader allocates both the 
ReaderBody and the bytes from a single allocation unit. 

Note: The storage for the SeiectionData is allocated when he Selection. Set is done and 
deallocated when ActOn [clear] is called. 

• Typical case: some storage associated with this Target, allow copy/move 

• Example: selection is a piece of a larger backing string and is maintained as an 
Environment.Block and Target ~ String. 

• Manager's global frame: 

myValueProcs: Selection. Va I ueProcs «- [ free: nil, copyMove: CopyMoveString ]; 
SelectionOata: type s record [ block: Environment.Block,... ]; 

- block represents the selectior). 

- block. pointer points to the backing string. 

• Manager's ConvertProc: 

OPEN selectionData: narrow [data, long pointer to SeiectionData]; | > 

RETURN [ [ 

value: zone.NEW [xstring. ReaderBody «- 

xstring.FromBlock [selectionData.block], 
ops: ©myValueProcs] ]; 

— Selection will put zone into the context field. 

— ops.f ree = nil means that FreeStd will be called. 

Here we allocate a ReaderBody that points directly into our backing string. Free will call 
FreeStd, which will free the ReaderBody. 

• Manager's CopyMoveString: 

OPEN zone: narrow [v.context, uncounted zone] ; 
OPEN selectionSubstring: narrow [v.value, xstnng.Reader] ; 
v.value <-xstring.CopyReader [ selectionSubstring, zone ]; 
zone. FREE [ ©selectionSubstring ]; -- frees the ReaderBody 

CopyReader copies both the ReaderBody and the bytes. After doing the copy, we free the 
ReaderBody. Note: After the copy. Free will still call FreeStd, which will free the copied 
ReaderBody and bytes. 

39.3.4 Detailed Flowchart of a Selection.Convert 

Following is the exact sequence of events that takes place in performing a I 
Selection.Convert, showing what the requestor does, what the manager does, and what 
Selection does. Various storage allocation cases arise, depending on the Target, what the 
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requestor wants to do, etc. Most of the cases are covered here. This will be most useful to 
managers, but anyone desiring an overall understanding of Selection will benefit from 
following these details. 

• Requestor calls Selection. Convert. 

• Convert calls the manager's ConvertProc. If the requestor provided a nil zone, Convert 
passes Heap.systemZone. 

• Manager constructs a Value, potentially allocating storage for value. value f and/or 
for value.context | . value.ops may or may not be provided, depending on the selection 
Target and the manager. Manager returns value to Convert. 

• If value.context is defaulted. Convert puts zone into value.context and returns to 
requestor. 

• If requestor just wants to look at the converted value (not copy or move it): 

• Requestor looks at value. value | . 

• Requestor calls Selection. Free [©value]; 

• If value.ops is NiLor value.ops.free is nil: 
Free calls FreeStd. 

FreeStd recovers the zone from value.context, does a zone. free 
[@value. value], and replaces value.ops with [free: NopFree, copyMove: nil]. 

• If value.ops.free is not NIL; 

• Free calls value.ops.free [©value] (that is, the manager's ValueFreeProc). 

• The manager's ValueFreeProc recovers the zone from value.context (possibly 
a field in a record pointed to by value.context) and releases any resources that 
were allocated in the ConvertProc. This includes not only the obvious freeing 
of storage from the zone (zone.FREE (@value. value] and/or Selection. FreeContext 
[@value, zone]), but also, for example, closing or deleting any files that were 
created. 

• END 

• If the requestor wants to move or copy the selection: 

• Requestor calls Selection. Move, Selection. Copy, or Selection. CopyMove, perhaps 
passing in data: long pointer , which points to a destination for the move/copy. 

If value.ops is nil or value. ops. copyMove is nil, CopyMove raises Error 
[InvalidOperation]. Otherwise, CopyMove calls value.ops.copyMove [@value, 
{copy, move}, data] (that is, the manager's ValueCopyMoveProc). 

The manager's ValueCopyMoveProc recovers the zone from value.context, gets 
the destination of the move/copy from data (if appropriate), does the move or copy. 
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calls Selection. FreeContext [@vaiue, zone] if necessary, does a zone. free 
[@oidValue. value] if necessary. Note: This is freeing the original value. value, not 
the copied one! Now the manager can either leave value. ops.free as is, or replace 
value. ops.free with selection. FreeStd (if the newly copied value was allocated from 
zone and zone is in value. context), or replace value. ops.free with 
Selection. NopFree (if there is nothing left to free). 

• CopyMove replaces value.ops. copy Move with nil to prevent another copy or move 
from being done. 

• Requestor may retain the copied value indefinitely and/or call Selection. Free to free 
the copied value after using it (see above). 

• END 



39.3.5 Sample ConvertProc and Requestor 

In this example of a simple selection manager, the selection is represented internally as a 
pair of indices within a single Mesa STRING. The string is inside a window. The indices 
designate the first character selected and the position beyond the last character selected. 
It isassume that there are several windows of this type, and that each contains a single 
string within which selections may be made. It is also assumed that the manager's module 
contains a procedure TextForWindow that obtains the string associated with a window, 
and various other obvious utilities and signals. The procedure Select makes a new 
selection. 

A ConvertProc is shown that implements the common targets. Observe the extremely 
heavy use of the defaults for the ops and context fields in the Value records. Since the 
Selection interface detects these defaults and applies the most common interpretations for 
Copy, Move, and Free, both the requestor and the manager are spared much of the coding 
effort. 

- use dynamic storage for data: global variables make savelrestore awkward 
myZone: UNCOUNTED ZONE = ... ; 
SelectionData: TYPE s record [ 

w: window.Handle, -- window containing this selection 

left, right: cardinal, 

marked: boolean false]; 

ValueContext: type a record [ - for use in Value.context fields 
zone: uncounted zone, 
w: Window.Handle]; 

Select: procedure [w: window.Handle, left, right: cardinal] = { 
text: long string = TextForWindow[w]; 

IF text = nil or left > text.length or right not in [left..text.length] then 

error BogusSelection; 
Selection.Set[ 

myZone.NEw[SelectionData <- [w, left, right]], 

ConvertSelection, ActOnSelection]}; 
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ConvertSelection: Selection.ConvertProc = { 

< <[data: ManagerData, target: Target zone: uncounted zone, info: Conversionlnfo] 

RETURNS [value: Value] > > 
OPEN seiectionOata: narrow [data, long pointer to SelectionDjata]; 
WITH i:info select from 
query = > 

FOR c: CARDINAL IN [O..LENGTH[i.query]) DO 
i.query[c].difficulty 

IF -^i.queryfc]. enumeration then select i.query[c].target from 
window, string, length, position « > easy, 
integer a > moderate, 
enocase s > impossible 
else -e/iumerated- IF i. query [c]. target = string then moderate 
ELSE impossible; 
endloop; 
convert » > 

SELECT target from 

window a > return[[ selectionData.w, seiection.nopFreeValueProcs]]; 

length a > RETURN[[zOne.NEW[L0NG CARDINAL 

seiectionOata. right - selectionData.left]]]; 
position a > RETURN([zone.NEw[LONG CARDINALS- selectionData.left]]]; 
string, integer = > 

IF seiectionData.right- selectionData.left > Seiection.maxStringLength then 
RETURN [Selection.n U 1 1 Va I ue] 

ELSE { 

bik: Environment.Block a [LOOPHOLE[@TextForWindow[rec.w].text], 

selectionData.left, seiectionData.right]; 
r: xstiing.ReaderBody ^xstring.FromBlock[blk]; 
IF target a integer then { 
bad: boolean false; 
num: LONG integer; 
num 't— xstring.StringToNumber[@r 

! xstring.lnvalidNumber, xstring.Overflow = > 
{bad true; continue}]; 
return[if bad then seiection.nuilValue else 
[zone.NEw[LONG integer <- num]]]}; 
— target = string 
return[[ 

value: zone.NEw[xstring.ReaderBody <- r], 
ops: @stringOps, 

context: zone.NEw[ValueContext [zone, selectionData.w]] ]]}; 

endcase; 

enumeration a > if target a string then { 

bIk: Environment.Block «- [LOOPHOLE[@TextForWindow[selectionData.w].text], 

selectionData.left, trash]; 
while block.startlndex < seiectionData.right do 
block.stopindexPlusOne <- 

MiN[block.startlndex + Seiection.maxStringLength, seiectionData.right]; 
IF l.proc[[ 

value: zone.NEw[xstring.ReaderBody <— xstring.FromBlock[bik]], 
ops: @stringOps, 

context: zone.NEw[ValueContext <~ [zone, selectionData.w]] ] 
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l.StOpTHEN exit; 

block.startlndex <- block.stopindexPlusOne; 

ENDLOOP}; 

endcase; 

RETURN[Selection.nuliVaiue]}; 

stringOps: Seiection.ValueProcs <— (FreeString, CopyString]; 

FreeString: Selection. ValueFreeProC" /^v: \/a/ueHand/ei-- = { 
context: long pointer to ValueContext ■ v.context; 

context.zone.FREE[@v. value]; -- free the ReaderBody, but not the text bytes 
Selection. FreeContext[ v, context.zone]}; 

CopyString: Selection.ValueCopyMoveProc « { 

<<[v: ValueHandle, op: CopyOrMove, data: long pointer] > > 
context: long pointer to ValueContext = v.context; 
old: xstring.Reader s v. value; 

IF op s move THEN error Seiection.Error[invalidOperation]; 

V. value <— xstring.CopyReader[old, context.zone]; 

context.zone.FREE[@old]; 

Selection. FreeContextC v, context.zone]; 

v.ops.free <— nil}; 

ActOnSelection: Selection.ActOnProc a { 

< <[data: ManagerData, action: Action] returns [cleared: boolean *- false] > > 
OPEN selectionData: narrow (data, long pointer to SelectionData]; 
SELECT action from 

mark, unmark = > if selectionData. marked # (action = mark) then 
InvertHighlightingfrec]; 

save, restore « > null; -- no special action need be taken 

delete = > null; - deletion is not allowed via this interface 

ciearlfHaslnsert ■ > null; -- assume that this tool never has the insertion point 

clear ■ > {myZone.FREE[@data]; cleared «-true}; 

endcase}; 

Here are three sample requestors that might invoke the above manager code. The first 
requestor wishes to interpret the selection, if possible, as a string of digits and obtain the 
corresponding integer value. The second wishes to open a file whose name is the current 
selection. (Assume the existence of an NSFile routine that deals with XString-format file 
names.) The third wishes to copy the current selection to a Stream unless the selection 
comprises more than 10000 characters Since copying an NSFile to an arbitrary Stream is 
awkward at best, it does not use Convertffiie], but rather attempts to get the selection as 
one or more strings to send to the Stream. 

- Example 1: obtain selection as an integer and do something with it 
num: long integer; 
ok: boolean; 

[ok, num] «-Seiection.ConvertNumber[lnteger] ; 

IF ok THEN { 

<< do whatever it was we wanted to do with num >>} 
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ELSE { 

< < report error, or ignore /t > > } ; 

- Example 2: use current selection as name of file to open 
v: Selection.Value <~Seiection.Convert[string]; 

file: NSFiie.Handle <- NSFiie.nullHandle; 

-- if V. value is nil it means there's no selection, or it can't be converted to a string, 

- or ttie string would be so long it's not a reasonable name anyway 

IF V.value #NIL THEN { 

file <-NSFiie.OpenByName[v.value ! NSFiie.Error a > continue]; 
Selection.Free[@v]}; 

- Example 3: copy selection to a Stream (handle is in sH) unless length > 10000 
bytes: long cardinal; ok: boolean; 

v: Seiection.Value; 

[ok, bytes] ♦-Seiection.ConvertNumber[length] ; 
IF ok AND bytes < = 10000 then { 

V ^ Selection.Convert(string]; 

IF v.value # NIL THEN PutReader[v, sH] 

ELSE [] Selection.EnumeratefPutReader, string, sH]}; 

PutReader: Seiection.EnumerationProc = { 

< < [element: Value, data: RequestorData] returns [stop: boolean <- false] > > 
sH: stream.Handie » data; 
sH.PutBlock[xstring.Block(element.value]. block 

\m0^ ! stream.TimeOut, voJume.lnsufficientSpace a > {stop ^ true; continue}]; 

Seiection.Free[@element]}; 

39.3.6 Sample Use of Enumeration 

In this example of the use of the enumeration facility, the user has asked to COPY or MOVE 
the selection to the desktop. The desktop does not particularly care what the selection is; it 
simply requires that it be rendered as one or more files. If the operation is a MOVE, it is 
better not to do it as a copy-then-delete; instead, obtain the existing files and relocate 
them. 

op: Selection. Copy Or Move <—...; setting is determined by the TIP table interpretor 
IF Seiection.Enumerate[CopyMoveFileToDesktop, file, @op].aborted then { - error - }; 



CopyMoveFileToOesktop: Seiection.EnumerationProc = { 
op: LONG POINTER TO Selection.CopyOrMove = data; 

file: LONG POINTER TO NSFiie. Reference <- element.value; -- this is readonly until Copied 
or Moved 

Selection.CopyMove[@element, op | , handleForDesktop 
! Selection. Error = > select code from 

" owner will not let us have it for some reason 
invalidOperation, operationFailed h > {stop true; continue}; 

ENDCASE a: > REJECT]; 

IF Stop THEN {Selection. Free[@element]; return}; 

file <— element.value; -- the value was probably changed by CopylMove 



39-27 



39 



Selection 



- file is now a Reference to a file that is of no interest to the selection manager 

< < create any associated structures necessary for keeping track of the icon > > 

< < might also need to set position attributes, etc.; it would be more efficient 
to set the attributes as part of the Copy or Move, but this would probably 
require an awkward structuring of CopyMove's data parameter > > 

Seiection.Free[@element]; - free the storage associated with the Reference 

}; 

Here are two cases where the above code might be invoked. First, assume the selection is a 
set of documents in an open folder. The folder's conversion proc calls 
CopyMoveFileToDesktop once for each document, with element being the 
NSFite. References for the already existing files. The ops. copy Move provided by the folder 
implementation either does an NSFiie.Copy or an NSFile.Move to transfer the file to the 
desktop directory, and updates element. value if necessary to refer to the new file. If the 
operation is a move, copyMove also reflects the deletion in the folder's window. It might 
also update the selection data if, for instance, the selection is represented internally as a 
range of positional indices within the directory. 

If the selection is a set of printers in the Star directory icon, no files exist for them until 
they are copied to the desktop. For each printer, the conversion procedure creates a file 
from scratch and passes it to CopyMoveFileToDesktop. This time, however, 
ops.copyMove calls NSFiLE.Move regardless of the operation requested, since it is not 
actually possible to remove objects from the Star directory. (Alternatively, it could call 
NSFile.Move to do a copy and raise Error[invalidOperation] if asked to do a move.) 
Meanwhile, the ops.f ree originally included with each element is SelectiorioNopFree; if the 
user chooses not to do anything with the printer, the Star directory enumeration code 
simply changes the attributes of the file to refer to the next printer in the enumeration and 
uses the same file again. Thus ops.copyMove must also set a flag indicating that a new 
dummy file must be created if there are any more elements in the enumeration. 

The important thing to note is that, in the first example, doing a copy involved creating a 
new file, whereas in the second example it didn't. (Instead, it needed to ensure that the file 
not be re-used when the enumeration continued.) There was no way for the requestor to 
decide whether the object needed to be copied. The decision was left up to the selection 
manager by means of the ops procedure. 
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39.4 Index of Interface Items 

Letters in parentheses indicate a description for a 

requestor (R) or a manager (M). 

Item " Page 



Action: TYPE 17 

ActOn: procedure 19 

ActOnProc: TYPE 13,17 

CanYouConvert: procedure 9 

Clear: PROCEDURE 19 

CiearOnMatch: PROCEDURE 19 

Conversionlnfo: TYPE 12,13,14 

Convert: procedure 5 

ConvertNumber: procedure 8 

ConvertProc: TYPE 12 

Copy: PROCEDURE 11 

CopyMove: ValueCopyMoveProc 11 

CopyOrMove: type 1 1(R), 16(M) 

Difficulty: type 9 

Discard: procedure 19 

Enumerate: procedure 10 

EnumerationProc: TYPE 10 

Error: error 20 

ErrorCode: type 20 

Free: procedure 8 

FreeContext: procedure 17 

FreeStd: ValueFreeProc 16 

HowHard: procedure 9 

ManagerData: type 12 



Item 



Page 



Match: procedure 
maxStringLength: cardinal 
Move: procedure 
NopFree: ValueFreeProc 



19 

10(R), 14(M) 

11 

16 



nopFreeValueProcs: long pointer to ValueProcs 17 
nuilValue: Value 5 
Query: procedure 9 
QueryElement: type 9(R), 13(M) 

Reconversion: SIGNAL 10 
ReconvertDuringEnumerate:PROCEDURElO 



RequestorData: type 
Restore: procedure 
SaveAndSet: procedure 
Saved: type 

Set: PROCEDURE 

Target: type 

UniqueAction: procedure 
UniqueTarget: procedure 
Value: type 
14(M) 

ValueCopyMoveProc: type 
ValueFreeProc: type 
ValueHandle: type 
ValueProcs: type 



10 
19 
18 
18 
12 
6 

20 
20 

5(R),13(M) 

11(R), 16(M) 
15 

8(R), 14(M) 
15 
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40.1 Overview 

The SimpleTextDisplay interface provides facilities for displaying, measuring, and 
resolving strings Xerox Character Code Standard text. SimpleTextDisplay deals with 
text in a single font—normally the standard system font—and does not support boldface, 
italic, sub- and superscript, and other text properties. SimpleTextDisplay does not 
implement editable or selectable text, but it provides the building blocks that can be used 
to implement such things. (See SimpleTextEdit.) 

Most clients will be interested mainly in the procedure StringlntoWindow, which simply 
displays one or more lines of text at a given location in a window. 

More sophisticated clients may want to use String! ntoBuffer, which formats te.xt into a 
special bitmap buffer rather than painting it into a window; MeasureString, which 
determines how wide a string would appear if painted into a window without actually 
painting it; or FillResolveBuffer, which computes the position of each character of an 
already-displayed line of text. 

All width values taken or returned by SimpleTextDisplay procedures are in terms of 
screen pixels (bits). 

40.2 Interface Items 

40.2.1 Simplest Way to Display Text 

StringlntoWindow: procedure [ 
string: xstring. Reader, 
window: wimdow. Handle, 
place: window.Place, 
lineWidth: cardinal <-cardinallast, 
maxNumberOf Lines: cardinal 

lineToLineDeltaY: cardinal <-0, -- default: systemFontHeight 
wordBreak: boolean*- true. 
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flags: Biteit.BitBltFlags <-oispiay.paintFlags] 
RETURNS [lines, lastUneWidth: caroinal]; 

Displays string in window, starting at place. Each line will be no more than lineWidth 
pixels wide, and there will be no more than maxNumberOfLines lines. If wordBreak is 
true. String! ntoWindow will try to break lines between, rather than within, words. The 
flags determine what BitBit function will be used to place the new bits in the window; the 
default is to OR them into the window's existing bitmap. When a new line is started, its y- 
position will be lineToLineDeltaY below the y-position of the previous line; if 
lineToLineOeltaY is defaulted to 0, each line will be systemFontHeight pixels below the 
previous one. lines is the number of lines that were actually painted. lastLineWidth is the 
width of the last line displayed. If the string ends with a carriage return and 
maxNumberOfLines are not exceeded, then lastLineWidth is 0 and lines include an empty 
line following that carriage return. If the string is empty, String! ntoWindow returns 
[lines: 0, lastLineWidth: 0]. 

StringlntoWindow always uses the standard system font, a Flushness of fromFirstChar, 
and a StreakSuccession of fromFirstChar. (See §40.2.4 for an explanation of Flushness and 
StreakSuccession.) 

systemFontHeight: readonly cardinal; 

systemFontHeight is the height (in pixels) of the system font. 



40.2.2 StringlntoBuffer 




StringlntoBuffer: procedure [ 
string: xstnng. Reader, 
bufferProc: BufferProc, 
I i neWidth : cardinal <- cardin al.last, 
wordBreak: boolean*- true, 

StreakSuccession: StreakSuccession <- fromFirstChar, 
font: SimpleTextFont.MappedFontHandie <-nil] 

RETURNS [lastLineWidth: cardinal, result: Result, rest: xstring.ReaderBody]; 

Formats string into a bitmap buffer using font and calls bufferProc for each line. (See 
BufferProc below for a description of the parameters passed to bufferProc.) If font is nil, 
the system font is used. StringlntoBuffer stops reading characters in the string and calls 
bufferProc when one of the following events occurs: 

• A carriage return is encountered. bufferProc will be called with a result of stop The 
string passed to bufferProc will end with the carriage return. 

• The lineWidth (measured in pixels) would be exceeded by formatting the next 
character. bufferProc will be called with a result of margin. The string passed to 
bufferProc will end with the last character that did fit (if wordBreak is false), or with 
the last character before the beginning of the word that did not fit (if wordBreak is 

TRUE). 
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• There are no more characters to be read. bufferProc will be called with a result of 
normal. The string passed to bufferProc will end with the last character of the string 
passed to StringlntoBuffer. 

Result: TYPE = {normal, margin, stop}; 

If result = normal, or bufferProc returns continue = false, StringlntoBuffer returns the 
following values: result = the result last passed to bufferProc, rest = a substring 
containing characters not yet processed (rest.offset will be the string. limit last passed to 
bufferProc), lastLineWidth = the dims, w last passed to bufferProc. 

If result is not normal, and bufferProc returns continue = true, StringlntoBuffer 

continues processing the remainder of string and calls bufferProc again. 

If string is empty, StringlntoBuffer returns [width: 0, result: normal, rest: 
xstring.nullReaderBody] and does not call bufferProc at all. 

BufferProc: type = procedure [ 
result: Result, 
string: xstring.Reader, 
address: Environment.BitAddress, 
dims: window. Dims, 
bitsPerUne: cardinal] 
RETURNS [continue: boolean]; 

A BufferProc is called once on each line of text processed by StringlntoBuffer. The 
procedure should return TRUE if it wants StringlntoBuffer to process the remaining text 
(and to call the BufferProc again). The parameters should be interpreted as follows: 

result explains why StringlntoBuffer decided to end the current line of text: 

stop if the line ends with a carriage return character. 

normal if there are no more characters to be processed after this line. In this case, 
StringlntoBuffer will ignore the continue boolean that the BufferProc 
returns. 

margin if the line was broken to avoid exceeding the lineWidth passed to 
StringlntoBuffer. 

string is a substring of the string passed to StringlntoBuffer, which contains exactly those 
characters on this line. If the line ends with a carriage return, the carriage return is the 
last character in string. 

address is the address of the bitmap buffer into which the current line's characters have 
been formatted. 

dims is the dimensions of the formatted part of the bitmap buffer, dims.h will always be 
equal to the height of font passed to StringlntoBuffer (or to systemFontHeight if font was 
nil), dims.w will always be < = the lineWidth passed to StringlntoBuffer. 

bitsPerLine is the number of bits per bitmap line in the buffer; that is, how many bits to 
add to address to reach the beginning of the next bitmap line. This will always be a 
multiple of 16. 
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Fine point: If the string passed to StringlntoBuffer ends in a carriage return, and the BufferProc returns TRUE, 
the BufferProc will be called one last time with an empty string (offset and limit both equal to the passed 
string.limit), an empty bitmap (dims.w = 0), and result = normal. 



40.2.3 Measure and Resolve 

GetCharWidth: procedure [char: xchar.Character, 
font: simpieTextFont.MappedFontHandle «-nil] 
RETURNS [width: cardinal] ; 

Returns the width of the specified character in the specified font. If font is nil, the 
system font is used. 

MeasureString: procedure [ 
string: xstring.Reader, 
I i neWidth : cardinal «- cardin al.last, 
wordBreak: boolean <- true, 

streakSuccession: StreakSuccession «-fromFirstChar, 

font: simpieTextFont.MappedFontHandle ^nil] 

returns [width: cardinal, result: Result, rest: xstring.ReaderBody]; 

MeasureString determines the number of horizontal pixels that would be taken up by 
displaying string in the specified font. If font is nil, the system font is used. If wordBreak 
is TRUE and the string will not fit into lineWidth pixels, MeasureString attempts to end the 
line between words, result is one of the fallowing: 

stop If a carriage return character is encountered in the string before lineWidth 
pixels have been measured out. In this case, width is the pixel width of those 
characters up to and including the carriage return, and rest begins with the 
first character following the carriage return. 

margin If the string will not fit within lineWidth horizontal pixels. In this case, width is 
the pixel width of those characters that do fit (possibly backed up to the end of 
the last word that entirely fits on the line, if wordBreak is true), and rest begins 
with the first character that does not fit. 

normal If the string contains no carriage returns and fits entirely within lineWidth 
horizontal pixels. In this case, rest is empty. 

If string is empty, MeasureString returns [width: 0, result: normal, rest: 
xstring.n ul I ReaderBody] . 

FiilResolveBuffer: procedure [ 
string: xstring.Reader, 
lineWidth: cardinal <- cardin al.last, 
wordBreak: boolean <- true, 

StreakSuccession: StreakSuccession «-fromFirstChar, 

resolve: ResovleBuffer, 

font: simpieTextFont.MappedFontHandle <-nil] 

returns [width: cardinal, result: Result, rest: xstring.ReaderBody]; 

FiilResolveBuffer measures the x-offset of the left edge of each character of string relative 
to the left edge of the leftmost character and stores the measurements in the resolve array. 
The measurements are in units of pixels. The offset of the leftmost character is zero. There 
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is one element in the resolve array for each of the bytes (not characters) of string. The 
^^■1^ measurement stored for each byte of string is the measure for the character that the byte is 

a part of. The measure stored for character set shift codes is that of the next actual 
character in the string. (For the meaning of the return values, see the description of 
MeasureString.) 

The resolve buffer must be string. limit-string. offset + 1 words long to avoid smashing 
memory. 

If string. context.suffixSize = 1 and the string contains no character set shifts (377Bs), that 
is,if there is one byte per character, then: 

resolve[0] is assigned x offset of the character string. bytes[string. offset], 
resolve[1] is assigned the x-offset of the character string. bytes[string. offset + 1], 

. . . . , 

resolve[string. limit-string. offset-1] is assigned the x-offset of the character 
string. bytes(string.limit-1]. 

If the string does contain 377Bs, then any character set shift bytes (L377B, chsetj or [377B, 
377B, 01) are assigned the same resolve value as the following character code byte. 

In any part of the string that is in Stringletl6 format (2 bytes per character), both bytes of 
each character are assigned the same resolve value. 

If a sequence of characters would be displayed as a ligature--a single graphic representing 
several adjacent characters— then all of those characters are assigned the same resolve 
value. 

= In all cases, resolve[string. limit-string. offset] is assigned the pixel width of the string; the 

same value that is given to the returned value width. 

If string is empty, FillResolveBuffer returns [width: 0, result: normal, rest: 
xstring.nullReaderBody] and does not write into the resolve buffer at all. 

ResolveBuffer: type = long descriptor for array [0..0) of cardinal; 

NewResoiveBuffer: procedure [words: cardinal] returns [ResolveBuffer]; 

Allocates a resolve buffer of the specified length for later use by FillResolveBuffer. Non- 
SimpleTextDisplay clients of TextBit are also encouraged to obtain their resolve buffers by 
calling this procedure, since SimpleTextDisplay caches resolve buffers for efficiency. 

FreeResolveBuffer: procedure [ResolveBuffer]; 

Frees a resolve buffer allocated by NewResoiveBuffer. 

40.2,4 Multinational Items 

Flushness: type = {flushLeft, flushRight, fromFirstChar}; 

A Flushness determines where to display a line of text that does not fill the entire bitmap 
width allotted to it. flushLeft means to place the leftmost character at the left edge of the 
bitmap. flushRight means to place the rightmost character at the right edge of the bitmap. 
fromFirstChar is equivalent to flushLeft if the first character of the text has 
xchar.JoinDirection « nextCharToRight (for example, Latin and most other alphabets); it 
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is equivalent to flushRight if the first character of the text has JoinDirection = 
nextCharToLeft (for example, Arabic and Hebrew letters). 

PeekForFlushness: procedure [requestedFlushness: Flushness, string: xstring.Reader] 
RETURNS [Flushness]; 

Returns a real flushness (either flushLeft or flushRight, not fromFirstChar) appropriate for 
the passed requestedFlushness and string. 

StreakSuccession: type « {leftToRight, rightToLeft, fromFirstChar}; 

PeekForStreakSuccession: procedure [ 

requestedStreakSuccession: StreakSuccession, string: xstring.Reader] 
RETURNS [StreakSuccession]; 

Returns a real streak succession (either leftToRight or rightToLeft, not fromFirstChar) 
appropriate for the passed requestedStreakSuccession and string. 

40.3 Usage/Examples 

The only non-Xerox Character Code that is significant to SimpleTextDisplay is Carriage 
Return. No other control characters are recognized. 

All width values taken or returned by SimpleTextDisplay procedures are in terms of 
screen pixels (bits). If the client passes his own font to SimpleTextDisplay, its mica widths 
should be equal to its pixel widths. Fonts passed to SimpleTextDisplay should have no 
measurements actually in micas. 

40.3.1 Stringlnto Window 

rb: xstring.ReaderBody ^ xstring.FromSTRING ["This is an example. "L]; 
[] <— SimpleTextDisplay. StringlntoWindow [ 

string: @rb, 

window: window, 

place: [10,10]]; 

40.3.2 StringlntoBuffer 

This example shows an implementation of StringlntoWindow using StringlntoBuffer. 

MyStringlntoWindow: procedure [ 
string: xstring.Reader, 
window: Window. Handle, 
place: window.Place, 
I i neWidth : cardinal «- cardin al.last, 
maxNumberOf Lines: cardinal 4-1, 
lineToLineDeltaY: cardinal «-0, 
wordBreak: boolean <- true, 
flags: BitBit.BitBltFlags ^Display.paintFlags] 
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RETURNS [lines: CARDINAL, lastLineWidth: caroinal] = { 

MyBufferProc: simpieTextDispiay.BufferProc = { 

Display. Bitmap [window, [place, dims], address, bitsPerLine, flags]; 
lines*- lines + 1; 

place. y place. y + lineToLineDeltaY; 

RETURN [continue: lines < maxNumberOfLines]; 

}; 

IF lineToLineDeltaY = 0 then lineToLineDeltaY «-simpieTextDispiay.systemFontHeight; 
lines <-0; 

[lastLineWidth: lastLineWidth] ♦-SimpleTextDisplay.StringlntoBuffer [ 
string: @rb, 

bufferProc: MyBufferProc, 
lineWidth: lineWidth, 
wordBreak: wordBreak]; 

}; 
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40.4 Index of Interface Items 



Item Page 

BufferProc: type 3 

GetCharWidth: PROCEDURE 4 

FillResolveBuffer: procedure 4 

Fiushness: type 5 

FreeResolveBuffer: procedure 5 

MeasureString: procedure 4 

NewResoiveBuffer: procedure 5 

PeekForFlushness: procedure 6 

PeekForStreakSuccession: procedure 6 

Result: type 3 

ResolveBuffer: type 5 

StreakSuccession: type 6 

String! ntoBuffer: procedure 2 

StringlntoWindow: procedure 1 

system FontH eight: readonly cardinal 2 
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41.1 Overview 



The SimpleTextEdit interface provides facilities for presenting short editable pieces of 
text, known as fields, to the user. The user can select, move, copy, delete, and edit the text. 
Such text can contain any sequence of characters supported by the Xerox Character Code 
Standard. 

All the text in a SimpleTextEdit field is displayed in a single font. Multiple fonts, boldface, 
italics, subscript, superscript, paragraph and character properties, and other elaborate 
editor features are not provided by SimpleTextEdit. 

SimpleTextEdit fields are most appropriate for short pieces of text, preferably less than 30 
lines long. They are not appropriate for editing entire files, for example. 

SimpleTextEdit is primarily intended to support text items in the higher-level 
FormWindow interface, but is also provided as a public interface for those clients who may 
need it. Most clients will want to use FormWindow rather than SimpleTextEdit. 
FormWindow provides support for general forms, including choice, boolean, and command 
items. FormWindow also automatically adjusts the position of other fields when a text 
field becomes taller or shorter. The client of SimpleTextEdit must provide its own 
procedure to do this. 



41.1.1 Creating Fields 



Fields are created by calling CreateField. Before creating any fields, however, a 
FieldContext must first be created by calling CreateFieldContext. There must be one 
FieldContext for each window that will contain Fields. The FieldContext returned by 
CreateFieldContext should be passed to CreateField for each field to be created. When a 
field is created, only the desired window. Dims of the field need to be supplied. 
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41.1.2 Displaying a Field 

A field is displayed by calling RepaintField. Before a field can be displayed, it must be 
given a window. Place by calling SetPlace. Failure to call SetPlace before displaying a field 
will result in Error [fieldlsNoPlace]. 



41.1.3 Notifying a Field 



Notifications are passed to a field by calling TIPResults. SimpleTextEdit does not attach a 
window dispiayProc nor a TiP.NotifyProc to a window. Rather, the client provides these 
procedures and then calls RepaintField for display and TIPResults for notifications. If there 
is more than one field in a window or a single field does not occupy an entire window, the 
client must resolve mouse buttons to determine which field should get the notification. 

41.2 Interface Items 



41.2.1 FieldContext 

FieldContext: TYPE a long pointer to FieldContextObject; 
FieldContextObject: type; 

CreateFieldContext: procedure [z: uncounted zone, window: Window.Handie, 
changeSizeProc: ChangeSizeProc, font: simpieTextFont.MappedFontHandle -h-nil] 
returns [fc: FieldContext]; 



A FieldContext holds information that is common to all Fields in a given window. There 
must be exactly one FieldContext associated with any window containing Fields. The 
FieldContext contains such information as the fields' font, the current input focus, the 
field containing the current selection, and so forth. 

CreateFieldContext creates a FieldContext for window, which can be later used to create 
individual Fields (see CreateField). Only one FieldContext should be created for any 
window. All storage associated with the FieldContext and its Fields is allocated from z. 
The changeSizeProc is called whenever any field's height is changed (see ChangeSizeProc 
below). All text in the FieldContext's fields will be displayed with the supplied font. If font 
is defaulted (the usual case), the standard system font is used. 

DeStroyFieldContext: procedure [fc: FieldContext]; 

DestroyFieldContext destroys a FieldContext. If any of fc's fields has the input focus, it 
clears the input focus and turns off the blinking caret. If any of fc's fields contains the^. 
current selection, it clears and dehighlights the selection. DestroyFieldContext does not 
destroy each field. The client should either call DestroyField on each field before calling 
DestroyFieldContext or else dispose of the associated uncounted zone after calling 
DestroyFieldContext. The client should not call DestroyField after calling 
DestroyFieldContext. 
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41.2.2 Creating Fields 

Field: TYPE = long pointer to FieldObject; 



FieldObject: type; 

CreateField: procedure [ 
clientData: long pointer, 
context: FieldContext, 
dims: window.Dims, 
initString: xstring.Reader <~nil, 

fiusliness: SimpieTextDisplay.Flushness <-fromFirstChar, 

streal<Succession: simpieTextDispiay.StrealcSuccession <-fromFirstChar, 

readonly, password: boolean «- false, 

fixedHeight: boolean <- false, 

font: simpieTextFont.MappedFontHandle «-nil, 

backingWrlter : xstrlng.Writer *- nil. 

SPECIALKeyboard: BlackKeys.Keyboard <-nil] 

RETURNS [f: Field]; 



A Field is an area within a window that contains editable text. It is the primary object 
manipulated by this interface. 

CreateField creates a field with appropriate attributes. The field will use the window, font, 
zone, and ChangeSizeProc of the passed FieldContext. 

clientData is a pointer which is not interpreted but is returned by GetClientData. Clients 
may use it to associate their own data with each individual field. 

dims are the initial dimensions of the field. As the field's contents change, its height may 
change as well (unless fixedHeight is true). However, the height will never become 
smaller than dims.h. 

initString is the initial contents of the field, if any. CreateField copies the string; the caller 
continues to own it when CreateField returns. 

f lushness controls where to place lines of text that do not fill the entire width of the field. If 
flushness = flushLeft, the leftmost character is next to the field's left edge. If f lushness = 
flushRight, the rightmost character is next to the field's right edge. If flushness = 
fromFirstChar, the field is flushLeft if its first character has xcharJoinDirection = 
nextCharToRight (for example, Latin and most other alphabets), and flushRight if the first 
character has JoinDirection = nextCharToLeft (for example, Arabic and Hebrew letters). 

streakSuccession indicates whether the text of the field flows leftToRight or rightToLeft. 
The default (fromFirstChar) causes the streakSuccession of the field to be determined from 
the first character in the field. Latin and most other alphabets flow leftToRight, Arabic 
and Hebrew flow rightToLeft. 

If readonly is true, the user cannot change the field's contents. SetlnputFocus is a no-op on 
a readonly field, and any call on TIPResults that would normally set the input focus to this 
field, or change the field's contents will not do so. However, SetValue still works on a 
readonly field. 

If password is true, each character of the field will be displayed as a *. If a selection is 
made within a password field, and that selection is moved or copied, * characters will be 
moved or copied rather than characters from the field's actual backing string. 
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Selection.Convert will also produce a string full of " characters. The only way to access a 
password field's actual content is to call GetValue. 

If fixedHeight is true, the field's height will never change regardless of the field's content. 
The context's ChangeSizeProc will never be called with this field as an argument. 

font allows each field to be a different font. If font is nil, then the system font is used. 
Note: This does not provide for general attributed text in SimpleTextEdit fields. The entire 
field is all the same font. 

If backingWriter is nil (the usual case), SimpleTextEdit allocates the field's backing string 
from the context's zone, expands it as needed, and deallocates it when the field is 
destroyed. If backingWriter is non-NiL, SimpleTextEdit uses it as the backing string and 
does not deallocate it when the field is destroyed. If backingWriter.zone is nil, TIPResults 
raises Error [noRoomlnWriter] whenever it tries to do an operation that would overflow 
the backing string. 

SPECIALKeyboard allows a client-specified interpretation of the central keypad. 
DestroyField: procedure [f : Field]; 

Destroys the passed field. If the field has the input focus, it clears the input focus and turns 
off the blinking caret. If the field contains the current selection, it clears and dehighlights 
the selection. DestroyField must not be called after the field's context has been destroyed. 

GetValue: procedure [f: Field] returns [xstring.ReaderBody]; 

Returns the field's current contents. The returned string points directly into the field's 
backing storage; it is not copied. 

SetValue: procedure [f: Field, string: xstring.Reader, repaint: boolean <- true]; 

Change the contents of the field. Copies the string, which the caller continues to own after 
SetValue returns. Repaints the field unless repaint is false. In that case, the caller should 
call RepaintField before returning to the notifier. If the field has the input focus, it clears 
the input focus and turns off the blinking caret. If the field has the selection, it clears and 
dehighlights the selection. If repaint is true, the field may become taller or shorter, 
triggering a call on the ChangeSizeProc. 



RepaintField: procedure [f : Field]; 

Repaints the field. 

SetPlace: procedure [f : Field, place: window.Place]; 

Changes the window-relative location of the field. This procedure must have been called at 
least once before calling GetBox, RepaintField, or TIPResults; otherwise, calling those 
procedures raises Error [fieldlsNoplace]. Does not repaint the field. SetPlace is intended for 
two primary uses: to set the initial location of a field, and to change it from within a 
ChangeSizeProc when another field is getting taller or shorter. 




41.2.3 Displaying a Field 
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41.2.4 Notifying a Field 



TIPResults: procedure [f : Field, results: TiP.Results] 
RETURNS (tooklnputFocus, changed: boolean]; 



Passes results to the specified field. The field is changed as appropriate. For example, if 
results contains a f^ointDown atom, the character closest to the cursor is highlighted. 
Details of the exact processing performed for each possible result are described below. If 
the field's contents are changed while processing the results, changed will be true. If the 
input focus was set to this field, tooklnputFocus will be true. Both booleans start out false 
but may become true when strings or atoms are encountered in results. Any TiP.Results 
that change the field's contents also cause the field to be repainted; this may cause the 
field to become taller or shorter, triggering a call on its ChangeSizeProc. 

If a string is encountered in results, the string is inserted into the field at the current 
insertion point. This clears the selection if the current insertion point is at either end of 
the selection. The passed field must be the current input focus and not readOnly; 
otherwise, the string is ignored. 

The following atoms in results cause actions to be taken. An * indicates that the passed 
field must be the current input focus; if not, the atom is ignored. Unless otherwise 
indicated, tooklnputFocus and changed remains unaffected after this atom is processed. 

AdjustOown (should be preceded by a coords result): Extends or contracts the current 
selection, depending on coords earlier in results. If there is no current selection, creates 
one extending from the current insertion point to a place determined by coords. This is a 
no-op if the passed field is not the current input focus or selection. 

AdjustMotion (should be preceded by a coords result): Same effect as AdjustDown, 
although a different algorithm is used to determine which endpoint of the selection is 
being moved. 

Backspace*: If the field is not readonly, deletes the character before the insertion point 
and sets changed to TRUE. This clears the selection if the current insertion point is at either 
end of the selection. 

BackWord*: If the field is not readonly, deletes the word before the insertion point and 
sets changed to true. This clears the selection if the current insertion point is at either end 
of the selection. If the field is a password field, acts like a Backspace. 

CopyDown: Calls TiPStar.SetMode [copy]. 

CopyModeOown (should be preceded by a coords result): If the field is not readonly, 
places the caret at an appropriate place in the field, depending upon coords earlier in 
results, but leaves the selection alone. tooklnputFocus will be true. If the field is 
readonly, this is a no-op and tooklnputFocus is unchanged. 

CopyModeMotion (should be preceded by a coords result): Same effect as 
CopyModeOown. 

CopyModeUp*: If the field is not readonly, inserts the current selection at the current 
insertion point, sets the selection to be the newly inserted text, and calls TiPStar.SetMode 
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[normal]. If the selection is not empty, repaints the field and sets changed to true. If the 
field is readonly, this is a no-op and changed remains unaffected. 

DeleteDown: Calls Selection.ActOn [delete], changed becomes true. 

MoveDown: Calls TiPStar.SetMode [move] 

MoveModeDown (should be preceded by a coords result): Same effect as 
CopyModeOown. 

MoveModeMotlon (should be preceded by a coords result): Same effect as 
Copy ModeDown . 

MoveModeUp*: Same effect as CopyModeUp, except that it does a Selection.ActOn [delete] 
on the current selection before setting the selection to be the newly inserted text. Note 
that if the current selection is in a readonly field, no deletion occurs, and it acts exactly 
like a CopyModeUp. 

NewLine*: If the field is not readonly, inserts an Ascii.CR at the current caret position. 
This clears the selection if the current insertion point is at either end of the selection, 
changed will be true. If the field is readOnly, is a no-op and changed is unaffected. 

NewParagraph*: Same effect as NewLine. 

PolntDown (should be preceded by a coords result and a time result): Sets the current 
selection to be in the passed field. The location of the selection depends upon coords earlier 
in results; the extent (character, word, paragraph) depends on its current extent and time 
earlier in results. tooklnputFocus is true unless the field is readonly. 

PointMotion (should be preceded by a coords result): Moves the current selection within 
the field. If the current selection is not in the field, it sets it there. The location of the 
selection depends upon coords earlier in results. The extent of the selection (character, 
word, paragraph) remains unchanged. tooklnputFocus is true unless the field is readonly. 

PointUp (should be preceded by a time result): Sets the last-click time , which determines 
whether a subsequent PolntDown represents a multiple-click. 

Stop: Calls TiPStar.SetMode [normal] 

41.2.5 Miscellaneous Get and Set Procedures 

GetBox: procedure [f : Field] returns [box: window. Box]; 

Returns the box (dimensions and place) currently occupied by f . box. place will be relative 
to the field's window, and is always be the last value passed to SetPlace. Raises Error 
[f ieldlsNoplace] if SetPlace has never been called on this field. 

GetClientData: procedure [f: Field] returns [clientData: long pointer]; 

Returns the clientData that was passed to CreateField. 

GetFieldContext: procedure [f : Field] returns [FieldContext]; 
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Returns the field context that was passed to CreateField. 
GetFlushness: procedure [f: Field] returns [simpieTextDispiay.Flushness]; 

Returns the current Flushness off. 

GetFont: procedure [f : Field] 

returns [simpieTextFont.MappedFontHandie]; 

GetlnputFocus: procedure [fc: FieldContext] returns [Field]; 

If some field associated with fc has the input focus, it returns that field; otherwise, it 
returns nil. 

GetCaretPlace: procedure [context: FieldContext] 
returns [place: window.Place]; 

If any field in the FieldContext contains the current type-in point, this procedure returns 
the location of that point. If not, place = [-1,-1]. This is useful for determining that the 
window must be scrolled to make the caret visible to the user. 

GetReadOnly: procedure [f: Field] returns [boolean]; 

Returns the current value of readonly for f. 

GetStreakSuccession: procedure [f: Field] returns [simpleTextDispiay.StreakSuccession]; 
Returns the current StreakSuccession off. 

GetWindow: procedure [fc: FieldContext] returns [window: window.Handle]; 

Returns the window that was passed to CreateFieldContext. 

GetZone: procedure [fc: FieldContext] returns [uncounted zone]; 

Returns the uncounted zone that was passed to CreateFieldContext. 

SetDlms: procedure [f : Field, dims: window.Dims]; 

SetOims sets the dimensions for f . 

SetFixedHeight: procedure [f : SimpieTextEdit.Field, 
fixedHeight: boolean]; 

Allows setting of the fixed height attribute for a field. 

SetFlushness: procedure [f : Field, new: SimpieTextDispiay.Flushness] 

RETURNS [old: SimpieTextDispiay.Flushness]; 

Changes the field's flushness and returns the old flushness. Does not repaint the field. 
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SetFont: procedure [f : Field, 

font: simpieTextFont.MappedFontHandle «-nil]; 

If font a NIL, the system font is used. 

SetlnputFocus: procedure [f: Field, beforeChar: cardinal <-cardinal.last] ; 

Sets the current input focus to be in this field and places the blinking caret before the 
specified character. If beforeChar is 0, puts the caret before the first character; if it is 
CARDINAL.LAST or Otherwise larger than the length of the backing string, the caret is placed 
after the last character in the field. Does not affect the current selection. 

SetReadOnly: procedure [f : Field, readonly: boolean] returns [old: boolean]; 

Changes the field's readonly attribute and returns its old value. If this field has the input 
focus and readOnly is true, clears the input focus and turns off the blinking caret. If this 
field has the selection and readOnly is false and old is true, sets the input focus to this 
field and places the caret after the last character in the selection. 

SetSelection: procedure [f: Field, 

firstChar: cardinal ^0, lastChar: cardinal ^cardinal.last]; 

Sets the current selection to be in this field, covering the specified range of characters. If 
firstChar is 0, the selection begins with the first character of the field. If lastChar is 
CARDINAL.LAST or Otherwise larger than the length of the backing string, the selection 
extends to the end of the string. Highlights the selection if it is not empty. Does not affect 
the input focus or caret. 

SetStreakSuccession: procedure [f : Field, new: simpieTextDispiay.StreakSuccession] 
returns [old: SimpieTextoispiay.StreakSuccession]; 

Changes the field's StreakSuccession and returns the old StreakSuccession. Does not 
repaint the field. 



41,2.6 ChangeSizeProc 



ChangeSizeProc: type = procedure [f : Field, oldHeight, newHeight: integer, 
repaint: boolean]; 

Each FieldContext has a ChangeSizeProc associated with it. This procedure is called 
whenever any of its fields is redisplayed and finds that the number of lines of text being 
displayed has changed. It may be called as a result of calling either RepaintFleld. 
TIPResults, or SetValue with repaint = true. The client is expected to update any affected 
data structures (such as the Window. Place of other fields) and then optionally repaint any 
part of the window that is invalid. (There are two exceptions: the ChangeSizeProc is never 
called on a field for which CreateField was called with fixedHeight s true, and it is not 
called if both the old and new number of text lines require fewer vertical pixels than the 
height dims.h that was specified to CreateField.) 

The oldHeight and newHeight parameters are in vertical pixels. inDisplayProc is true if 
the ChangeSizeProc is being called as a result of calling RepaintField with repaint « true: 
(that is, is being called indirectly by Window. Validate). 
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If repaint is true, the ChangeSizeProc should not do a window. Validate, since this would 
cause undesirable recursion. 

41.2.7 Errors 

Error: error [type: ErrorTypej; 

ErrorType: type = {fieldlsNoplace, noRoomlnWriter, lastCharGTfirstChar}; 

Error [fieldlsNoplace] is raised by GetBox, RepaintField, and TIPResults if SetPlace has 
never been called on the passed field. Error [noRoomlnWriter] is raised by CreateField, 
SetValue, and TIPResults if a non-NiL backingWriter was passed to CreateField, the 
backingWriter has a nil zone, and the desired operation would overflow the string. 

41.3 Usage/Examples 

41.3.1. Selection Management 

If certain atoms (PointDown, PointMotion, AdjustOown, AdjustMotion, CopyModeUp, 
MoveModeUp) are in the TiP.Results passed to TIPResults, SimpleTextEdit may become the 
manager of the current selection. The procedure SetSelection also causes SimpleTextEdit 
to manage the curent selection. 

While SimpleTextEdit is managing the current selection, it supports conversions to the 
^Hpi^ following Selection.Targets: shell, subwindow, length, and string. It also supports 

Selection. Enumerate with a target of string. 

SimpleTextEdit implements the following Seiection.Actionsimark, unmark, clear, delete, 
clearlfHaslnsert, restore, and save. All other Actions are ignored. 

Selection.ActOn [delete] automatically repaints the field that contained the current 
selection; the field may become taller or shorter, triggering a call on its ChangeSizeProc. 
Selection.ActOn [delete] is a no-op if the current selection is in a readOnly field. 
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41.4 Index of Interface Items 



Item 


Page 


ChangeSizeProc: type 


8 


CreateField: procedure 


3 


CreateFieldContext: procedure 


2 


Destroy Field: procedure 


4 


DestroyFieldContext: procedure 


2 


Error: error 


9 


ErrorType: type 


9 


Field: type 


3 


FieldContext: type 


2 


FieldContextObject: type 


2 


FieldObject: type 


3 


GetBox: procedure 


7 


GetCaretPlace: procedure 


7 


GetClientData: procedure 


7 


GetFieldContext: procedure 


7 


GetFlushness: procedure 


7 


GetFont: procedure 


7 


GetlnputFocus: procedure 


7 


GetReadOniy: procedure 


7 


GetStreakSuccession: procedure 


7 


GetValue: procedure 


4 


GetWindow: procedure 


7 


GetZone: procedure 


7 


RepaintField: procedure 


4 


SetOims: procedure 


7 


SetFixedHeight: procedure 


8 


SetFlushness: procedure 


8 


SetFont: procedure 


8 


Setin put Focus: procedure 


8 


SetPlace: procedure 


4 


SetReadOnly: procedure 


8 


SetSelectlon: procedure 


8 


SetStreakSuccession: procedure 


8 


SetValue: procedure 


4 


TIPReSultS: PROCEDURE 


5 
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SimpleTextFont 



42.1 Overview 



The SimpleTextFont interface provides access to the default system font that is used to 
display Viewpoint's text, such as the text in menus, the attention window, window name 
stripes, containers, property sheet text items, and so forth. This interface is a 
specialization of the regular font management subsystem. 

42.2 Interface Items 

42.2.1 System Font 

MappedFontOescriptor: type; 

MappedFontHandle: TYPE = long pointer to MappedFontOescriptor; 

MappedFontOescriptor is an opaque type that contains all of the information about a font. 
(All metrics, including the width of each character, are in screen dots, not micas.) 

MappedOefaultFont: procedure returns [MappedFontHandle]; 

MappedOefaultFont returns the client a handle onto the system default font. May raise 
FontNotFound or Problem[badFontl. The implementation of SimpleTextFont expects that 
the default font is available on the system volume, in the System catalog, with the name 
System. Font. 

MappedFont: procedure [name: xstring.Reader<~ nil] 
returns i; MappedFontHandle]; 

MappedFont returns a handle onto the named system font. Supplying nil is the equivalent 
of calling MappedOefaultFont. May raise FontNotFound or Problem[badFont]. 

UnmapFont: procedure [MappedFontHandle]; 

Unmaps a font that was mapped with SimpleTextFont.MappedFont. 
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42.2.2 Client-Defined Characters 




AddClientDefinedCharacter: procedure [ 
width, height: cardinal, 
bitsPerLine: cardinal, 

bits: LONG POINTER, 

offsetlntoBits: cardinal 0 ] 
RETURNS [xstring.Character]; 

AddCiientDefinedCharacter adds the client's bitmap to the system font as a new character 
and returns the sixteen-bit value of the character position it is assigned. The new 
character's TextBIt flags indicate that it is neither a stop nor a pad character. At start-up 
time, at least 100 slots are available for these new characters. [0,26] normally displays as 
the blob character. May raise Problem[clientCharacterBitsExhausted] or 
Problem(clientCharacterCodesExhausted]. If RESUMEd the character [0,26] is returned. 

The Xerox Character Code Standard sets aside a block of character codes for user 
definition. (See the Xerox Rendering Code Standard, XSIS 068208 page 6.) In Star, it is 
often useful to include a small picture, for example, a 13x13 icon drawing, within a 
message or other text. 

The AddClientDefinedCharacter procedure provides a convenient way of presenting such 
little pictures within formatted system text. You create a character for the picture, say in 
initialization code, and then simply use that (16-bit) character within ordinary text 
sequences, such as window titles. 



FontNotFound: signal [name: xstring.Readerj; 
If FontNotFound is resumed, the system font is used. 
Problem: signal [code: ProblemCode]; 
ProblemCode: type = 

{badFont, clientCharacterCodesExhausted, clientCharacterBitsExhausted}; 



SimpleTextFont is a specialization of the regular font management subsystem. 

The font file format is easily parsed, it can be mappable into read-only virtual memory for 
use, and it can be extended. A single file defines the bitmaps for the Xerox characters in 

one font face and one font size, such as Bodoni Italic 10. Fine Point: In the case in which several 
different font face/sizes have the same pictures, as can occur with some printwheel fonts, you would wish to use 
the same file for more than one font/face. This subject is outside the scope of this specialized interface, since we are 
only dealing with one font. 

The font file begins with a header that identifies the font and describes the subsequent 
sections. Each subsequent section then contains TextBlt-style information about one 




42.2.3 Signals and Errors 



42.3 Usage/Examples 
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character set's characters. Fine Point: Descriptions of the font management subsystem and the ViewPoint 
font format are to be found elsewhere. 

42.3.1 Adding a Client- Defined Character 

The following example creates a small (13x13) icon and displays it as part of a string: 
myBits: array [0..13) of word [-some bits-]; 

wb: xstring.WriterBody <-xstrmg.WriterBodyFromSTRING[" is an icon."]; 
smailPictuirerxstring.Character SimpieTextFont.AddClientDef inedCharacter [ 

width: 13, 

height: 13, 

bitsPerline: 16, 

bits: @myBits, 

offsetlntoBits: 0]; 

xstring.AppendChar[to: @wb, c: smallPicture]; 

[] ^SimpleTextDisplay.StringlntoWindow [ 
string: xstring.ReaderFromWriter[@wb], 
window: window, 
place: place]; 

42.3.2 Acquiring the System Font 

The following example acquires a handle to the system font: 

systemFont: SjmpieTextFont.MappedFontHandle = simpleTextFont.MappedFont[]; 
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42.4 Index of Interface Items 



Item 


1 age 


AddClientOefinedCharacterrpROCEDURE 


2 


FontNotFound: SIGNAL 


2 


MappedDefaultFont:PROCEDURE 


1 


Mapped Font:PROCEDURE 


1 


MappedFontDescriptor:TYPE 


1 


MappedFontHandle:TYPE 


1 


Problem . SIGNAL 


2 


ProblemCode:TYPE 


2 


UnmapFont: procedure 


1 



42-4 



43 



SoftKeys 



43.1 Overview 

The SoftKeys interface provides for client-defined function keys designated to be the 
isolated row of function keys at the top of the physical keyboard. It also provides a 
SoftKeys window whose "keytops" may be selected with the mouse to simulate pressing of 
the physical key on the keyboard. Such a window will be displayed on the user's desktop 
whenever an interpretation other than the default SoftKeys interpretation is in effect. 
[The default is assumed to be the functions inscribed on the physical keys.) 

43.2 Interface Items 

43.2.1 Data Structures for SoftKey Labels 

numberOfKeys: cardinal = 8; — This number is dependent on ttie physical Iceyboard. 

Fine Point: SoftKeysExtra also exports a variable, numberOfKeys of type CARDINAL. This interface supports 
applications responding to both the 6085 and 8010 keyboards. See §43.3.2 for more details. 

Represents the number of keys in the soft key row. 

LabelRecord; TYPE = record [ 

unshifted: xstring.ReaderBody <-xstring.nuliReaderBody, 
shifted: xstring.ReaderBody <- xstring.nullReaderBodyj; 

LabelRecord provides a record of two XString.ReaderBody arrays so that both the shifted 
and unshifted key meanings may be labeled. It is expected that any individual key will 
have either a single unshifted label centered on the picture of the appropriate keytop or 
both shifted and unshifted labels painted in two lines on the keytop or no label at all 
(xstring.nullReaderBody for both shifted and unshifted). 

Labels: type = longdescriptorfor array of LabelRecord; 

Client-owned array of strings to be used as labels on the SoftKeys virtual keytops. The 
SoftKeys procedures will expect an array of up to numberOfKeys LabelRecord's at a time. 
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Clients should see to it that string deallocation does not occur between calls to create and 
delete a SoftKeys instance. 

Bitmaps may be specified for individual labels by using 
SimpleTextFont.AddClientDefinedCharacter. The current SimpleTextFont implementation 
has a somewhat limited number of available slots for client-defined keys. (See the 
SimpleTextFont interface for more information.) , 

43.2.2 Creating and Deleting SoftKeys 

Push: PROCEDURE [ 

table: TiP.Table <-nil, 
notifyProc: TiP.NotifyProc *-nil, 
labels: Labels^ NIL, 
highlightedKey: cardinal <- nullKey, 
outiinedKey: cardinal <- nullKey] 
RETURNS[window: Window. Handle]; 

Push installs the SoftKeys interpretation by: (1) If there is a non-NiL table, it will be 
installed in the tip watershed (see TIPStar); (2) if there is a non-NiL notifyProc, it will be 
attached to NormalKeyboard.TIP. The latter has the effect of passing all productions matched 
in NormalKeyboard.TIP to your notifyProc. (See Appendix A for a complete listing of 
NormalKeyboard.TIP.) 

A SoftKeys window is displayed using labels to "inscribe" the keytop pictures with the 
new names of the keys. Both the shifted and unshifted state of a key may be labeled. If 
only the unshifted state is relevant, the shifted state may be defaulted to 
xstring.nuilReaderBody. If there are fewer strings than keytops needing them, the 
remaining keys are left blank. Extra strings are ignored. Fine Point: Bitmaps may be placed on the 
keytops by using simpieTextFont.AddClientOefinedCharacter. Storage for the label strings is the 
responsibility of the client. Care should be taken to ensure that this storage is kept intact 
between a Push and a Remove of any given SoftKeys interpretation. 

outiinedKey and highlightedKey appear highlighted and/or outlined when the window is 
initialized. The default is no outlining or highlighting. Key values assume zero indexing 
[O..SoftKeysExtra.numberOfKeys). ( That is, the key marked Center is key 0, Bold is key I, 
etc.) 

Push returns a handle to the client's SoftKeys window. Note: There may be more than 
one SoftKeys window, with each client holding the handle to his own. The last Pushed 
interpretation is the one in effect until it is Removed or superseded by another Push. 

Remove: procedure [window: window. Handle]; 

The Remove procedure removes the SoftKeys interpretation and associated SoftKeys 
window. The client is responsible for removing his SoftKeys interpretation when he 
relinquishes control of the selection/input focus [see Selection interface descriptions of 
ActOn and Clear] or the user's attention (as in the case of the keyboard and font keys). A 
SoftKeys window and its associated SoftKeys interpretation constitute a unique SoftKeys 
instance. Any SoftKeys instance may be removed from the stackof SoftKeys instances in 
an order other than the order pushed. 
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. Attempts to Remove without the corresponding valid window handle from a Push results 

in the error InvalidHandle. 

Fine Point: Remove, rather than Pop, was chosen to describe the function opposite Push to clarify that this is not 
a true stack. While Push, as the name implies, acts on the top of the stack, Remove does not. It is possible to 
Remove a SoftKeys window from other than the top of the stack. 

Swap: PROCEDURE [ 

window: window.Handle, 
table: Tip.Table <-nil, 
notifyProc: Tip.NotifyProc <-nil, 
labels: Labels«~NiL, 
highlightedKey: cardinal «- nullKey, 
outlinedKey: cardinal <-nullKey]; 

The Swap procedure is a means of exchanging SoftKeys interpretations without changing 
the SoftKeys instance. Current examples of use include the keyboard key implementation 
where pressing the "More" key brings up another group of SoftKeys choices. It is strongly 
suggested that a client utilizing a "More" key place it on the first soft key (the key marked 
CENTER on the physical keyboard) for a consistent user interface. 



At the time when no SoftKeys interpretation is desired, a single Remove is expected 
corresponding to the original Push. Any number of Swaps may occur in between. 
Attempts to Swap without the corresponding valid window handle from a Push results in 
the error InvalidHandle. 

43.2.3 Highlighting and Outlining a SoftKeys Keytop Picture 



HighlightThisKey: procedure [ 
window: window.Handle 
key :CARDINAL nullKey]; 

OutlineThisKey: procedure | 
window: window.Handle, 
key: cardinal <-nuliKey]; 



These procedures are provided for those clients where permanent highlighting and/or 
outlining of certain soft keys is desired. (Do not confuse these procedures with the 
highlighting done when a key is selected with the mouse. That highlighting is done 
without client participation.) The first parameter, window, refers to the client's SoftKeys 
window returned from a Push. The cardinal corresponds to the key (zero indexing) to be 
outlined or highlighted whenever the chosen key changes, A key value of null Key has the 
effect of undoing a key that is currently highlighted (or outlined). A number other than 
nullKey or [O..SoftKeysExtra.numberOfKeys) results in NoOp. 

Attempts to call HighlightThisKey or OutlineThisKey without a valid handle from a Push 
will result in the error InvalidHandle. 

nullKey: cardinal = last(cardinal1; 

A default value meaning no key, to be used for outlinedKey and highlightedKey. 
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43.2.4 Retrieving Information About a SoftKeys Window Instance 

Info: PROCEDURE [ 

window: window. Handle] 

RETURNS [ 

table: Tip.Table. 
notifyProc: tip. Notify Proc, 
labels: Labels, 
highlightedKey:CAROiNAU 
out! i ned Key : cardinal] ; 

Tlie Info procedure returns information relevant to the SoftKeys instance related to 
window. If the window handle is not valid, the error InvalidHandle will be returned. 



43.2.5 Errors 

InvalidHandle: error; 

This error is raised if the SoftKeys window handle passed to Remove, Swap, Info, 
HighlightThisKey, or OutlineThisKey is invalid. 

43.3 Usage/Examples 



43.3.1 Graphics Example 




—When the selection is such that the graphics code ta/res control, 
— the initial graphics code should put up the graphics softkeys: 
graphicsSoftKeysWindow Push[ 

table: graphicsSoftKeysTIPTable, 

labels: graphicsSoftKeyLabeis]; 

—where the core of the graphics TiP.Table looks something like: 
—leftside values are defined in the LevellVKeys interface 

SELECT TRIGGER FROM 

CenterDown => Stretch; 

BoidDown = > Magnify; 

ItalicsDown = > Grid; 

CaseOown, UnderlineDown = > Line; 

DbkUnderiineDown, SuperscriptDown = > Curve; 

StrikeoutOown, SubscriptDown = > Join; 

SuperSubOown, SmallerDown = > Top; 

endcase; 

—and part of the graphics tip. NotifyProc resembles the following: 
—leftside values are the atom results from the tip, Table 
atom => SELECT result FROM 

Stretch = > DoMyStretchRoutine[]; 

Magnify => DoMyMagnifyRoutine[]; 

Grid => DoMyGridRoutineH; 

Line DoMyLineRoutineH; 

Curve => DoMyCurveRoutineH; 
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Join => DoMyJoinRoutine[]; 
Top = > DoMyTopRoutineH; 
endcase; 

"When graphics loses the selection, it must clear away its SoftKeys interpretation. 
RemovelgraphicsSoftKeysWindow]; 

A client using More as one of his soft keys handles it in his TiP.Tables and Tip.NotifyProc: 

TIP. Table entry: 

Center Down = > More; 

Notif yProc entry: 
More a > Swap[ 
window: mySoftKeysWindow, 
table: myNextSoftKeysTIPTable, 
labels: myNextSoftKeyLabels, 
highlightedkey: 1]; 

This entry results in an exchange of the client's last SoftKeys interpretation for the next 
one specified, (namely, the installation of the new TiP.Table and new labels on the key tops.) 
The second key (bold on the physical keyboard) will be highlighted in the SoftKeys 
window. The outlinedKey parameter has been left blank. This defaults to nullKey, in 
which case no key will be outlined. 

43.3.2 Keyboard Manager Example 

This client's (Keyboard Manager) select arm does the right thing for both the 8010 and 
6086 workstation keyboards. 

atom a > select Z.a FROM 

CenterDown = > IF more THENSoftKeys.Swap [] else InstallKeyboard [labell]; 
BoldDown a > InstallKeyboard [Iabel2]; 
ItalicsDown a > InstallKeyboard [labels]; 
CaseDown, UnderlineDown = > InstallKeyboard [Iabel4]; 
DbkUnderlineDown, SuperscriptDown = > InstallKeyboard (labels); 
StrikeoutDown, SubscriptDown = > InstallKeyboard [Iabel6]; 
SuperSubDown = > InstallKeyboard [label?]; No label? if the machine is an 

8010. 

DbkSmallerDown = > InstallKeyboard [labels]; - No labels for 8010 either. 
MarginsDown, SmallerDown = > ShowKeyboard []; 
FontDown, DefaultsDown a > SetKeyboard []; 

If the user presses the MarginsDown on a 6085 or the SmallerDown on an 8010, he has 
actually invoked the soft key that is labeled SHOW in the soft keys window visible on the 
screen. 
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43.4 Index of Interface Items 



Item Page 

HighlightThisKey: PROCEDURE 3 

Info: PROCEDURE 4 

InvalidHandie: error 4 

Label Record . TYPE 1 

Labels: type 1 

nullKey: CARDINAL 3 

numberOfKeys: cardinal 1 

OutlineThisKey: PROCEDURE 3 

Push: PROCEDURE 2 

Remove: procedure 2 

Swap: procedure 3 
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44.1 Overview 



The StarDesktop interface provides access to assorted facilities related to the ViewPoint 
desktop. 



44.2 Interface Items 



44.2.1 General 



AddReferenceToDesktop: procedure [ 
reference:NSFile.Reference, 
place.window. Place nextPlace]; 

nextPlace: Window. Place = [-1,-1]; 

Adds an icon to the desktop. The file (reference) must be a child of the desktop file (see 
GetCurrentDesktopFile below.) If there is already an icon at place, the next available 
place is used. 

GetPlaceFromReference: procedure [ref : NSFiie.Reference] 

RETURNS [Window.Place]; 

This returns the location of an icon on the desktop. It may be used with 
AddReferenceToDesktop to place an icon near another icon by passing the return value 
from GetPlaceFromReference to AddReferenceToDesktop. AddReferenceToDesktop 

places the new icon at the next available spot after the place passed in. 

SelectReference: procedure [reference: NSFiie.Reference] 
RETURNS [ok: boolean]; 

Selects the icon associated with the specified reference. SelectReference returns false if 
selection fails (for example, if the reference is not found on the desktop). 
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GetWindow: procedure returns [window: window. Handle]; 




Returns the desktop window (that is, the root window for ViewPoint). 

GetShellFromReference: procedure [ref : NSFiie.Reference] 
returns [sws: StarWindowShell.Handle]; 

If an icon has a shell currently opened, GetShellFromReference returns this shell. 

CreateDesktop: procedure [name: xstring.Reader] 
RETURNS [fh: NSFiie.Handlel; 

Creates a new desktop directory and returns a handle to it. name is typically a fully 
qualified three-part user name. It is used by logon plug-in clients, a friends-level facility 
(as opposed to a public facility). 

GetCurrentDesktopFile: procedure returns [NSFiie.Reference]; 

Every available desktop is an NSFile with attribute. isDIrectory = true. Desktops have 
children that are also NSFiles and show up as icons on the desktop (see the ViewPoint 
Programmer's Guide, chapter 3, for more information). GetCurrentDesktopFile returns 
the NSFiie.Reference for the desktop NSFile that is currently installed and displayed to the 
user. 

GetNextUnobscuredBox: procedure [height: integer] returns [window. Box]; 

GetNextUnobscuredBox returns the next available vertical segment of the desktop 
window of height, height, and width the width of the desktop. This is intended for such 
things as the Attention window and the typing feedback window for. JStar There is no 
guarantee that the box returned will be visible, i.e., the client must ensure that the 
returned box is within the desktop window. 

SetDisplayBackgroundProc: procedure [procedure [window.Handle] ]; 

SetOisplayBackgroundProc allows a client to change the procedure that displays the 
background for the desktop. 



44.2.2 Atoms 



Several ATOMs are exported by the StarDesktop: 



attemptingLogoff 



"AttemptingLogoff: Event just before logoff. Can be 
vetoed. Gives clients a chance to veto logoff. 



desktopWindowAvaiiable 



"DesktopWindowAvailable": Event notified when 
the desktop window has been initialized and inserted 
into the window tree. Cannot be vetoed. 



fullUserName 



"FuUUserName": This atom is to be used with 
AtomicProfile. 
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newlcon "Newlcon": Event notified when an icon has been 

added to the desktop, either by user copy/move, or by 
a client call to AddReferenceToDesktop. 

logoff' "Logoff: Event occurs after logoff. Cannot be vetoed. 

logon "Logon": Event notified after successful Star logon. 

Cannot be vetoed. 

userPassword "UserPassword": Also to be used with AtomlcProf ile. 

44.3 Usage/Examples 

44.3.1 Adding a Reference to the Desktop 

BuildFlle: PROCEDURE [-parms— 7 * { 
reference: NSFiie.Reference <<r- 

InitiallizeFile [parent: starDesktop.,GetCurrentDesktopFile[] ]; — local proc 
place: wiindow.Place «- [...]; 



starDesktop.AddReferenceToDesktop [reference, place]; 

}; 

44.3.2 LogonProc and Display-Background-Proc Use 

MyLogonProc: ENTRY starOesktop.LogonProc s { 
" perform a logon and If successful returns true. 
" probably entails use o/ AtomicProfile interface. 
fullName: xstring.ReaderBody <- 
password: xstring.ReaderBody 

AtomlcProf ile.SetString [starDesktop.fullUserName, @fulllName]; 
AtomicProfile.SetString [starDesktop.userPassword, ©password]; 



}; 

— Mainline code 

IFstarDesktop.GetLogonProc [] = NIL THEN [] <-starDesktop.SetLogonProc [MyLogonProc]; 
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44.4 Index of Interface Items 



Item Page 

AddReferenceToDesktop: procedure 1 

attemptingLogoff : Atom.ATOM 2 

CreateOesktop: procedure 2 

desktopWindowAvaiiable: Atom.ATOM 2 

fuliUserName: Atom.ATOM 2 

GetCurrentDesktopFile: procedure 2 

GetNextUnobscuredBox: procedure 2 

GetPlaceFromReference: procedure 1 

GetShellFromReference: procedure 2 

GetWindow: procedure 2 

nextPlace: constant 1 

newlcon: Atom.ATOM 2 

SetDisplayBackgroundProc: procedure 3 

SelectReference: procedure 1 

Logoff: Atom.ATOM 3 

Logon: Atom.ATOM 3 

userPassword: Atom.ATOM 3 



StarWindowShell 



45.1 Overview 



StarWindowShell allows a client to create a Star-like window. A StarWindowShell 
window has a header that contains a title, commands, and popup menus. It may have both 
horizontal and vertical scrollbars. It has interior window space that may contain anything 
the client desires (see Figure 45.1.) StarWindowShell also supports the notion of "opening 
within." The client is insulated from the implementation-specific details of exactly how 
these features are represented on the display as well as how windows are arranged on the 
screen (for example, whether they overlap). 

45.1.1 Client overview 



A StarWindowShell is a window (see Window interface) that is a child of the desktop 
window. A StarWindowShell has an interior window that is a child of the 
StarWindowShell and is exactly the size of the available window space in the shell; that 
is, the StarWindowShell minus its borders and header and scrollbars. The interior window 
may have child windows created by the client. These children of the interior window are 
called body windows. The client may create an arbitrary number of body windows and 
may arrange them in an arbitrary fashion. Note: Since the body windows are children of 
the interior window, they are clipped by the interior window. Therefore a client could, for 
example, create a body window that is very much taller than the interior window and 
accomplish, scrolling by simply sliding the body window around inside the interior window 
(This is actually what the default StarWindowShell scrolling does; for more detail, see the 
section on scrolling). 

The StarWindowShell interface provides a number of facilities for manipulating 
StarWindowShells and their various parts: creating and destroying a StarWindowShell; 
using body windows, commands and popup menus; client TransitionProcs (called 
whenever a StarWindowShell changes state-is opened or closed for example); scrolling ; 
AdjustProcs and LimitProcs; and displaying and stacking (that is, open-within) 
StarWindowShells. The most commonly used facilities (creating a StarWindowShell and 
body windows) are described here and in the section on interface items. The less commonly 
used facilities are described in each subsection of the interface items. 
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StarWindowShell 
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Figure 45.1 A Star window shell 



45.1.2 Creating a StarWindowShell, Handles, etc. 



A StarWindowShell is created by calling StarWindowShell. Create. There are no required 
parameters, but it is quite common to provide a name and a transitionProc. The name is 
displayed as the title in the StarWindowShell header. The transitionProc is called 
whenever the StarWindowShell is opened, destroyed, or "put to sleep," giving the client an 
opportunity to allocate and deallocate storage, open and close files, and so forth. 



StarWindowShell.Create returns a StarWindowShell. Handle. A StarWindowShell. Handle is a 
RECORD [window. Handle]. Thus any procedure that takes a window. Handle also takes a 
StarWindowShell.Handle, but not the other way around. (The Mesa compiler automatically 
strips off the brackets and passes the window. Handle if a StarWindowShell.Handle is passed). 
In particular, a context may be hung directly off a StarWindowShelKsee the Context 
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interface). The Handle returned by Create is then used as the first parameter to most other 
^1^^ calls to StarWindowSheil. 

The StarWindowSheil returned by Create is not displayed on the screen; that is, it. is not 
inserted into the visible window tree. A StarWindowSheil may be inserted into the 
window tree by calling StarWindowShell.Push. This is usually not done by the client but 
rather by some other part of ViewPoint, such as the desktop implementation. For example, 
when the user selects an icon and presses OPEN or PROPS, the application (actually the 
application's Containee.GenericProc) creates a StarWindowSheil and returns it. The 
desktop implementation then displays the StarWindowSheil by doing a 
StarWindowShell.Push. 

45,1.3 Body Windovi^s 

Body windows are created by calling StarWindowSheil. CreateBody. This returns a 
Window.Handle. The client can create an arbitrary number of body windows. Each body 
window will be a child of the StarWindowShell's interior window. The body windows may 
overlap or not. They can actually be in any arrangement the client finds useful. Some 
common arrangements of body windows are as follows: 

•One very long body window. 

This is easy to scroll by simply sliding the body window, which is what the 
StarWindowSheil default scolling does. 

tOne body window with BodyWindowJustFits = TRUE. 

This is one way to display an infinite amount of data, such as a Tajo-like editor. The 
client must keep track of what is currently in the window, use AdjustProcs, do 
scrolling, and so forth. This is difficult to implement. 

•Several body windows about the size of the interior, adjacent, non-overlapping. 

This is another way to display an infinite amount of data. The client lets 
StarWindowSheil do default scrolling, which slides the body windows up or down and 
then calls the client to supply more body windows when it runs out. The client might 
put one page of text into each body window, supplying pages to- StarWindowSheil 
scrolling as needed. 

•Several body windows smaller than the interior, adjacent, non-overlapping. 
This can be used to simulate subwindows. 

Notes Body windows can themselves have child windows, and so on. A client might 
implement frames in a document editor by making each frame a child of a body window. 

The eldest body window may be obtained by calling StarWindowSheil. GetBody. All the body 
windows may be enumerated by calling starWindowSheli.EnumerateBodieslnDecreasingY or 
StarWindowSheil. EnumerateBodieslnlncreaslngY. To get the StarWindowSheil from any 

body window, use StarWindowSheil. ShellFromChild. Fine point: The client's body windows may not be 
the only child windows of the interior window, and the interior window may not be the only child of the 
StarWindowSheil window. Therefore the client should never try to enumerate body windows by calling 
Window.GetChiild and Window.GetSibling starting with the StarWindowSheil, and the client should never try to get 
^IbP''^ the StarWindowSheil from a body window by calling window.GetParent. 
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The client may provide a repaintProc and a bodyNotifyProc with each body window. The 
repaintProc is the display procedure that is called by the Window implementation 
whenever part or all of the window needs to be displayed (see window. SetDisplayProc). The 
bodyNotifyProc is a tip. Notify Proc that is attached to the window along with the normal 
set of TIP tables and receives notifications for the window (see 
TIP. SetNotifyProcAndTable). Note: If the client is going to use some ViewPoint interface to 
turn the body window into a particular type of window (such as Form Window or 
ContainerWindow), these procedures should not be supplied by the client, but rather will 
be supplied by that interface. 

A single body window can be set to fit into the interior window. Any time the 
StarWindowShell's size is changed, the body window's size is changed accordingly. (See 
SetBodyWindowJustFits.) 

45.1.4 Commands and Menus 

Every StarWindowShell can have commands and popup menus, as in Figure. 45.1. 
Commands are actually individual menu items (MenuOata.ltemHandle), where the 
MenuOata.ltemName appears with a rounded corner box around it. When the user clicks 
over a command, the MenuData.MenuProc for that item is called. Commands are specified 
by calling StarWindowShell. SetRegularCommands, which takes a MenuOata.MenuHandle. 
Each item in the menu is displayed as a command on the left side of the header. 

A popup menu is an entire menu. The menu's title appears with a rounded corner bo.x 
around it on the right side of the shell's header. When the user buttons down over the 
menu's title, a small window appears next to the poimter with one line for each menu 
item. When the user selects one of the items, that item's MenuData.MenuProc is called. 
Popup menus are specified by calling starWindowShell.AddPopupMenu. 

Facilities are also provided for specifying commands that should appear when a shell has 
other shells opened on top of or within it. See the section on Push and Pop for a full 
discussion of the "open within" illusion, and the section on commands and menus for a full 
discussion of these extra commands. 

45.2 Interface Items 

45.2.1 Create a StarWindowShell, etc. 

Create: procedure! 

transitionProc: TransitionProc «— nil, 

name:xstring.Reader <— nil, 

namePicture:xstring.Character <- xchar.null, 

host: Handle nil, 

type: ShellType regular, 

sleeps: boolean false, 

considerShowingCoverSheet: boolean <- true, 

currentlyShowingCoverSheet: boolean «- false, 

pushersAreReadonly: boolean <- false, 

readonly: boolean <- false, 

scrollData: ScrollData vanillaScrollData, 
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garbageColiectBodiesProc: procedure [Handle] <-nil, 
isCloseLegalProc: IsCloseKegalProc <-Niu 
bodyGravity: window. Gravity <— nw, 
zone: uncounted zone <- nil] 
RETURNS [Handle]; 

Create makes a StarWindowShell and returns a Handle to it. The StarWindowShell 
returned by Create is not displayed on the screen (is not inserted into the window tree). A 
StarWindowShell may be inserted into the window tree by calling StarWindowShell. Push. 
This is usually not done by the client, but rather by some other part of ViewPoint, such as 
the desktop implementation. For example, when the user selects an icon and presses OPEN 
or PROPS, the application (actually the application's Containee.GenericProc) creates a 
StarWindowShell and returns it. The desktop implementation then displays the 
StarWindowShell by doing a StarWindowShell. Push. 

transitionPiroc is a procedure that is called whenever the state of the shell is about to 
change. In particular, it is called just before the shell is destroyed. The client uses a 
transitionProc to free any data structures that may have been allocated and associated 
with the shell. TransitionProcs are discussed in later in this chapter. 

name appears as the title in the header of the StarWindowShell. 

namePicture appears just before the title in the header. It is common for this character to 
be a small icon picture created by SimpleTextFont.AddClientDef inedCharacter. 

host is a StarWindowShell that this shell is logically attached to. The host shell will not 
be destroyed while this shell Is open. This is typically used by property sheets to indicate 
the shell that the property sheet is displaying properties of. If host is nil, closing this shell 
will not depend on any other shell. 

type is the type of the shell. Shell placement algorithms may be affected by the type. For 
example, regular shells will not overlap when displayed with Star-style window 
management, while psheet shells may overlap other shells. 

sleeps indicates whether this shell can go into the sleeping StarWindowShell. State. If it is 
false, we assume that the client software does not take advantage of the possibilities of the 
sleeping State (by remembering data from open to open). This argument is used in 
conjunction with the client's transitionProc, discussed later in this chapter. 

considerShowingCoverSheet and currentlyShowingCoverSheet indicate whether the 
shell should ever possess a cover sheet and, if so, whether the cover sheet should be 
currently visible. What appears in any cover sheet is governed by a cover sheet 
implementation. See the section on Errors. 

The two readonly arguments define whether this shell is uneditable, and whether all 
shells pushed onto this one should be uneditable. readonlyness is really up to client 
interpretation. This information is simply maintained for client convenience. If a shell 
below this one in a push stack has pushersAreReadonly set true, then the implementation 
forces readonly to true. 

scrollData indicates whether vertical or horizontal scrollbars should appear and allows the 
client to supply procedures to be called for various user scrolling actions. (See the section 
on scrolling for full details.) The default will cause vertical scrollbars to appear, but not 
horizontal. The default scrolling procedures simply slide body windows up or down, left or 
right, as appropriate. 
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garbageCollectBodiesProc is called when a scroll action causes a body window to be placed 
so that it is completely outside the shell's interior window. The call thus allows the client 
an opportunity to garbage-collect the body window and associated data structures. (See 
the section on Scrolling.) 

isCloseLegaiProc is called when the user attempts to close the StarWindowShell, or when 
a client calls StandardClose, StandardCloseAll, or StandardCloseEverything. This allows 
the client to veto the user's attempt to close the window. If the isCloseLegaiProc returns 
TRUE, the shell is closed; if the IsCloseLegaiProc returns false, the shell is not closed. The 
isCloseLegaiProc is also a convenient way for the client to get control when the window is 
being closed. 

bodyGravity argument indicates what value for gravity should be used when the 
implementation adjusts the size of a body window. 

All storage related to the shell will be allocated out of zone. If zone ~ nil, 

StarWindowShell will provide its own zone. Fine point: The window.Objects themselves are not 
allocated out of the client's zone. This means that if the client allocates child windows using a zone ( window.Create 
or Window.New with non-NIL zone), these child windows must be removed from the shell before it is destroyed. 
When the shell's TransitionProc is called with a state of dead, the client should remove those windows. 

Handle: TYPE « record [window.Handlej; 

Create returns a Handle. Any procedure that takes a window. Handle also takes a 
StarWindowShell. Handle, but not the other way around. (The Mesa compiler automatically 
strips off the brackets and passes the window. Handle if a StarWindowShell. Handle is passed). 
In particular, a Context may be hung directly off a StarWindowShell (see the Context 
interface). The Handle returned by Create is then used as the first parameter to most other 
calls to StarWindowShell. 

nullHandle: Handle s [nil]; 

nullHandie is provided as a convenience, since nil is often not an appropriate value for a 
StarWindowShell. Handle. 

IsCloseLegaiProc: TYPE s procedure [sws: Handle, 
closeAll: BOOLEAN <- false] returns [boolean]; 

closeAli indicates whether the user selected Close or CloseAll. 

Destroy: procedure [ sws: Handle]; 

Destroys the StarWindowShell and associated data. Will call the client's transitionProc 
with state = dead. May raise Error [notASWS]. 

ShellType: type = {regular(O), keyboard, psheet, attention, static, last(1 5)}; 

ShellType influences how a shell behaves in several regards, regular shells have a ? 
command, a Close command, and a CloseAll command if opened on top of another shell. 
With Star-like overall screen management, regular shells do not overlap; rather they 
change size whenever a window is opened or closed, psheet shells do not have any 
StarWindowShell-supplied commands and freely overlap other shells, psheet shells are 
used by the PropertySheet interface to create property sheets, static shells are exempted 
from any overall screen management; for example, a static shell is not shrunk to make 
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room for a regular shell when the overall screen management is Star-like. Some clients 
may find this useful. Most clients will not use keyboard, psheet, or attention types. 

StandardClose: procedure [sws: Handle] returns [Handle]; 

StandardCloseAll: procedure [sws: Handle] returns [Handle]; 

StandardClose and StandardCloseAll provide procedural access to the Close and Close All 
commands that are placed in a shell's header automatically by StarWindowShell. These 
procedures call the client's IsCloseLegalProc and transitionProc, just as if the user had 
selected the command. May raise Error [notASWS]. 

StandardCloseEverything: procedure returns [notCIosed: Handle]; 

StandardCloseEverything closes all open StarWindowShells. Logoff uses this procedure. 
notCIosed is the first window that could not be closed because its IsCloseLegalProc 
returned false. All windows that can be closed will be. If notCIosed is nil, then all windows 
were closed. 

NewStandardCloseEverything: public procedure 

returns [numberLeftOpen: cardinal <-0, lastNotClosed: Handle nullHandle]; 

This procedure is the same as StandardCloseEverything except that it also returns the 
number of shells that vetoed close. Fine Point: This procedure is currently exported tlirough 
StarWindowS hell Extra . 

SetPreferredDims: procedure [ sws: Handle, dims: window.Dims ]; 
SetPreferredPlace: procedure [sws: Handle, place: wndow. Place]; 

SetPreferredDims and SetPreferredPlace provide a suggestion as to the desired size and 
location of the shell. Depending on the overall screen management in effect at the time the 
shell is displayed, these preferred values may be ignored. May raise Error [notASWS]. 

SetPreferredlnte.riorOims: procedure [sws: Handle, dims: Window.Dims]; 

SetPreferredlnteriorDims makes the shell just big enough to fit around dims. This means 

the interior window will be of size dims. Fine Point: This procedure is currently exported through 
StarWindow£;hellExtra2. 



45.2.1.1 IsCloseLegalProc 

The client may supply an IsCloseLegalProc when a StarWindowShell is created or later by 
calling SetlsCloseLegalProc. This client procedure is called when the user attempts to 
close the StarWindowShell, or when a client calls StandardClose, StandardCloseAll, or 
StandardCloseEverything. This allows the client to veto the user's attempt to close the 
window. If the IsCloseLegalProc returns true, the shell is closed; if the IsCloseLegalProc 
returns false, the shell is not closed. The IsCloseLegalProc is also a convenient way for the 
client to get control when the window is being closed. 
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IsCloseLegai: procedure [ sws: Handle. closeAli: boolean] returns [boolean]; 

IsCioseLegal calls the client's isCloseLegalProc and returns the value returned from that 
call. If there is no isCloseLegalProc, IsCioseLegal returns true. May raise Error [notASWS]. 

IsCIoseLegalProcReturnsFalse: IsCloseLegalProc; 

GetlsCloseLegalProc: procedure [sws: Handle] 
returns [ IsCloseLegalProc ]; 

GetlsCloseLegalProc returns the current isCloseLegalProc associated with sws. May raise 
Error [notASWS]. 

SetlsCloseLegalProc: procedure [ 
sws: Handle, 
proc: IsCloseLegalProc ]; 

SetlsCloseLegalProc sets the isCloseLegalProc for sws. May raise Error [notASWS]. 

Note: IsCloseLegalProc: type » procedure [... should be in this interface and will be added 
in the next release. 

45.2.1.2 Miscellaneous Get and Set Procedures 

Several procedures are provided that set and return values logically associated with a 
StarWindowShell. 

GetContainee: procedure [sws: Handle] returns [containee.Oata]; 
GetHost: procedure [sws: Handle] returns [Handle]; 
GetReadonly: procedure [sws:Handle] returns [boolean] ; 
GetType: procedure [sws:Handle]RETURNS[ShellType]; 

These procedures return the obvious value associated with sws. May raise Error 
[notASWS]. 

GetZone: procedure [sws: Handle] returns [uncounted zone]; 

The StarWindowShell implementation creates a zone when aStarWindowShell is created 
and uses the zone as storage for all shell-related items, such as name strings. The client 
can use this zone, knowing that the zone will be completely garbage-collected when the 
shell is destroyed. GetZone returns this zone. May raise Error [notASWS]. 

HaveOisplayedParasite: procedure [sws: Handle] returns [boolean]; 

HaveDisplayedParasite returns true if a shell is displayed that has this shell (sws) as its 
host. (See host under StarWindowShell. Create.) For example, if a property sheet is currently 
displayed that was created with host = sws, then HaveOisplayedParasite [sws] returns 
true. May raise Error [notASWS]. 
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SetContainee: procedure [sws: Handle, file: containee.DataHandle]; 

SetHost: procedure [sws, host: Handle] returns [old: Handle]; 

SetName: procedure [sws: Handle, name: xstring. Reader]; 

SetNamePicture: procedure [sws: Handle, picture: xstring. Character]; 

SetReadOnly: procedure [sws: Handle, yes: boolean]; 

SetSleeps: procedure [sws: starwindowsheii. Handle, sleeps: boolean] 
RETURNS [old: boolean]; 

sleeps = TRUE means the shell can be put to sleep. This is the same as the sleeps parameter 
to Create. Fine Point: This procedure is currently exported througli StarWindowShellExtra. 

These procedures set the obvious value associated with sws. May raise Error [notASWS]. 

45.2.2 Body Windov/s 

A StarWindowShell is a window (see Window interface) that is a child of the desktop 
window. A StarWindowShell has an interior window that is a child of the 
StarWindowShelland is exactly the size of the available window space in the shell, that is, 
the StarWindowShell minus its borders and header and scrollbars. The interior window 
may have child windows created by the client. These children of the interior window are 
called body windows. The client may create an arbitrary number of body windows and 
may arrange them in an arbitrary fashion. Note: Since the body windows are children of 
the interior window, they are clipped by the interior window. Therefore, a client could, for 
example, create a body window that is very much taller than the interior window and 
accomplish scrolling by simply sliding the body window around inside the interior 
window. (This is actually what the default StarWindowShell scrolling does; for more 
detail, see the section on scrolling). 

Body windows are created by calling StarWindowSheH.CreateBody. This returns a 
Window. Handle. The client can create an arbitrary number of body windows. Each body 
window will be a child of the StarWindowShell's interior window. The body windows may 
overlap or not. They can actually be in any arrangement the client finds useful. Some 
common arrangements of body windows are as follows: 

•One very long body window. 

This is easy to scroll by simply sliding the body window, which is what the 
StarWfindowShell default scrolling does. 

•One body window with BodyWindowJustFits = true. 

This is one way to display an infinite amount of data, such as. a Tajo-like editor. The 
client must keep track of what is currently in the window, use AdjustProcs, do 
scrolling, and so forth. This is difficult to implement. 

•Several body windows about the size of the interior, adjacent, non-overlapping. 

This is another way to display an infinite amount of data. The client lets 
StarWindowShell do default scrolling, which slides the body windows up or down and 
then calls the client to supply more body windows when it runs out. The client might 
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put one page of text into each body window, supplying pages to StarWindowShell 
scrolling as needed. 




•Several body windows smaller than the interior, adjacent, non-overlapping. 
This can be used to simulate subwindows. 
Note: Body windows can themselves have child windows, and so on. A client might 
implement frames in a document editor by making each frame a child of a body window. 

CreateBody: procedure [ 
sws: Handle, 

repaintProc: procedure [window.Handle] <-niu 
bodyNotifyProc: TiP.NotifyProc <-NfL, 

box: window.Box [[0,0l,[0,29999]] ] returns [window.Handle]; 

CreateBody creates a body window that is a child of the interior window of sws. 
repaintProc is the display proc that is called by the Window implementation whenever 
part or all of the body window needs to be displayed (see window.SetDisplayProc). 
bodyNotifyProc is a TiP.NotifyProc that is attached to the window along with the normal 
set of TIP tables and receive notifications for the window (see TiP.SetNotifyProcAndTable 
and TiPStar.NormalTable). Note: If the client is going to use some ViewPoint interface to 
turn the body window into a particular type of window (such as FormWindow or 
ContainerWindow), these procedures should not be supplied by the client, but rather will 
be supplied by that interface, box indicates the size and location of the body window 
within the shell's interior window. If box. dims. w and/or box. dims. h is zero, the body 
window will take on the dims.w and/or dims.h of the shell's interior window. May raise 
Error [notASWS]. 

DestroyBody: procedure [body: window.Handle]; 

DestroyBody destroys body and any Context data associated with it. May raise Error 
[notASWS]. 

GetBody: procedure [sws: Handle] returns [window.Handle]; 

GetBody returns the eldest body window of sws. Fine Point: The client's body windows may not be 
the only child windows of the interior window and the interior window may not be the only child of the 
StarWindowShell window. Therefore, the client should never try to enumerate body windows by calling 
window.GetChild and window.GetSibling starting with the StarWindowShell. May raise Error [notASWS]. 

ShellFromChild: procedure [child: Window.Handle] returns [Handle]; 

ShellFromChild returns the shell given any body window. Fine Point: The client's body windows 
may not be the only child windows of the interior window and the interior window may not be the only child of the 
StarWindowShell window. Therefore, the client should never try to get the StarWindowShell from a body 
window by calling window.GetParent. May raise Error [notASWS]. 

EnumerateBodieslnlncreasingY: procedure [ 

sws: Handle, proc: BodyEnumProc] returns [window.Handle <— nil]; 

EnumerateBodiesinDecreasingY: procedure [ 

sws: Handle, proc: BodyEnumProc] returns [window.Handle <— nil]; 
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BodyEnumProc: TYPE = procedure [victim: window.Handle] 

RETURNS [stop: BOOLEAN <- FALSE]," 

The EnumerateBodiesln... procedures enumerate all the body windows of sws, calling proc 
for each body window until proc returns stop = true. EnumerateBodieslnlncreasingY 
enumerates the body windows in increasing order of window. GetBox [body]. place. y, and 
EnumerateBodieslnDecreasingY enumerates the body windows in decreasing order of 
Window. GetBox [body]. place. y. Each procedure returns the last body window enumerated, 
or NIL if all body windows were enumerated. These procedures are especially handy for 
clients that do their own scrolling. To minimize repainting when scrolling a set of body 
windows upward it is important to move the upper ones first, and vice versa. May raise 
Error [notASWS]. 

GetBodyWiindowJustFits: procedure [sws: Handle] returns [ boolean]; 
SetBodyWindowJustFits: procedure [sws: Handle, yes: boolean]; 

Some clients may wish to have a single body window that is automatically resized by the 
StarWindowShell implementation to just fit within the interior of the shell. Such a body 
window is said to have BodyWindowJustFits = true. If BodyWindowJustFits = false (the 
default for CreateBody), the body window's dimensions are left alone by 
StarWindowShell, even though the body window may stick out or not fill the shell. 
GetBodyWiindowJustFits and SetBodyWindowJustFits allow the client to determine and 
set this just-fits behavior for a single body window. Setting just-fits when there is more 
than one body window yields undefined results. May raise Error [notASWS]. 

GetAvailableBodyWindowDims: procedure [sws: Handle] 

RETURNS [window.Dims]; 

GetAvailableBodyWindowDims returns the current dimensions of the interior window of 
sws. May raise Error [notASWS]. 

IsBodyWindowOutOflnterior: procedure [body: window.Handle] 

RETURNS [BOOLEAN]; 

IsBodyWindowOutOflnterior returns true if any part of body is sticking out of the 
interior window of its shell. May raise Error [notASWS]. 

InstallBody: procedure [sws: Handle, body: window.Handle]; 

InstallBody installs a previously created window into a StarWindowShell, thus making 
the windov/ a body window. Most clients will not need to use this procedure. May raise 
Error [notASWS]. 

OestallBody: procedure [ body: window.Handle]; 

DestallBody removes body from its StarWindowShell. Most clients will not need to use 
this procedure. May raise Error [notASWS], 
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45.2<.3 Commands and Menus 

Every StarWindowShell can have commands and popup menus, as in Figure 47.1. 
Commands are actually individual menu items (MenuData.ltemHandle), where the 
MenuOata.ltemName appears with a rounded corner box around it. When the user clicks 
over a command, the MenuData.MenuProc for that item is called. Commands are specified 
by calling StarWindowShell. SetRegularCommands, which takes a MenuData.MenuHandle. 
Each item in the menu is displayed as a command on the left side of the header. 

A popup menu is an entire menu. The menu's title appears with a rounded corner box 
around it on the right side of the shell's header. When the user buttons down over the 
menu's title, a small window appears next to the pointer with one line for each menu item. 
When the user selects one of the items, that item's MenuData.MenuProc is called. Popup 
menus are specified by calling StarWindowShell.AddPopupMenu. 

The Window.Handle that is passed to the MenuData.MenuProc for a command or popup menu 
item is the Window.Handle for the StarWindowShell that the command or popup menu is 
currently displayed in. 

StarWindowShells that are of type regular (see StarWindowShell. ShellType) will always have 
system commands leftmost in the header. When a shell is directly on the desktop, the 
system commands are ? (help) and Close. When a shell is opened within another, the 
system commands are ? (help), Close, and Close All . 

Note: Commands may be added to and removed from a StarWindowShell by using 
MenuData.Addltem, etc. Fine Point for current Star implementors: This is not the way to get such commands 
as ShowNext to appear and dissappear. See the sections on Push and Pushee Commands below. 

The implementation automatically overflows the rightmost commands into an overflow 
popup menu when all of them will not fit in the header. If all the popup menus won't fit in 
the header, the items from the leftmost ones are overflowed into the rightmost popup 
menu. The rightmost popup menu is always guaranteed to be displayed, since shells are 
not allowed to be so small that no popup menu will fit. 

SetRegularCommands: procedure [ 

sws: Handle, commands: MenuData.MenuHandle] ; 

SetRegularCommands associates commands with sws. May raise Error [notASWS]. 

GetRegularCommands: procedure [sws: Handle] 
RETURNS [MenuData.MenuHandle]; 

GetReguiarCommands returns the regular commands associated with sws. May raise 
Error [notASWS]. 

AddPopupMenu: procedure [ 

sws: Handle, menu: MenuData.MenuHandle] ; 

AddPopupMenu adds menu to the available popup menus in sws. The title of menu is 
displayed in the StarWindowShell header with the small popup menu symbol (s) just to 
the left of it, all enclosed in a rounded corner box. Note: Any arbitrary symbol (less than 
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the height of the system font) can be part of the title by using 
SimpleTextFont.AddClientDefinedCharacter. May raise Error [notASWS]. 

SubtractPopupMenu: procedure [ 

sws: Handle, menu: MenuOata.MenuHandle] ; 

SubtractPopupMenu removes menu from sws. May raise Error [notASWS]. 

EnumeratePopupMenus: procedure [sws: Handle, proc: MenuEnumProc]; 

Enumerates the popup menus associated with the shell. 

EnumerateAllMenus: procedure [sws: Handle, proc: MenuEnumProc]; 

Enumerates every menu visible in the shell. This includes popups, regular commands, 
tOpPushee commands from the shell underneath, etc. Fine Point: This procedure is currently 
exported through StarWindowShellExtra. 

MenuEnumProc: type = procedure [menu: MenuOata.MenuHandle] 
returns [stop: boolean <- false]; 

45.2.3.1 Pushee Commands 

Facilities are also provided for specifying commands that should appear when a shell has 
had other shells opened on top of or within it. These facilities are useful only to a client 
that implements some type of open-within capability, such as folders and file drawers. 
(See the section on commands and menus for a full discussion of the "open within" 
illusion.) These extra commands come in three sets: the set that should be displayed when 
this shell is just below the top of the install stack, the set that should be displayed when 
this shell is anywhere in the install stack, and the set that should be displayed if this shell 
is at the bottom of an install stack. These are the so-called TopPushee, MiddlePushee, and 
BottomPushee commands. 

Figure 47.2 depicts how these pushee commands, if supplied, will affect the commands 
visible in a given shell's header. In Figure 47.2, Shell B is Pushed on top of Shell A and 
Shell C is Pushed on top of Shell B. If Shell A is the only shell displayed, Shell A's system 
and regular commands appear in the shell's header. With Shell B Pushed on top of Shell A, 
Shell B's system and regular commands appear as well as Shell A's bottom pushee, middle 
pushee, and top pushee comimands. This is because Shell A is on the bottom, in the middle, 
and just below the top of the stack of shells. With Shell C Pushed on top of Shell B, Shell 
A's bottom pushee and middle pushee commands appear, but not Shell A's top pushee 
commands. Shell B's top pushee and middle pushee commands appear, but not its bottom 
pushee commands. 

Caution: The window. Handle passed to the MenuData.MenuProc for any pushee command is 
the window. Handle of the StarWIndowShell that the command is currently displayed in, 
not the StarWindowShell that the command was originally associated with. If the client 
wants to be able to recover the StarWindowShell that the command was originally 
associated with, it may be saved as the MenuData.ltemData. 
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SetBottomPusheeCommands: procedure [ 

sws: Handle, commands: MenuData.MenuHandle] ; 

SetMiddlePusheeCommands: procedure [ 

sws: Handle, commands: MenuData.MenuHandle] ; 

SetTopPusheeCommands: procedure [ 

sws: Handle, commands: MenuData.MenuHandle] ; 

GetPusheeCommands: procedure [sws: Handle] 

RETURNS [bottom, middle, top: MenuData.MenuHandle]; 

May raise Error [notASWS]. 
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Figure 45-2. Install Stack of Window Shells 
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45.2.4 TransitionProcs 

A StarWindowShell is always in one of three states: awake, sleeping, or dead. The awake 

state indicates that the shell is currently displayed. The sleeping state indicates that the 
shell still exists but is not being displayed and therefore resources associated with the 
display state should be freed. The dead state indicates the shell is about to be destroyed 
and therefore all resources associated with the shell should be freed. 

Every StarWindowShell can have a client supplied TransitionProc associated with it. This 
TransltionProc will be called whenever the shell's state changes. The client may then do 
whatever is necessary in terms of allocating or freeing resources. 

The client may call starWindowShell.Create [ ... sleeps: false ... ] to indicate that the 
application does nothing interesting with the sleeping state. This may cause routines that 
would otherwise put the shell in sleeping state (say on a close, where it might be quickly 
reopened) to put it in dead state instead. 

State: TYPE a {awake(O), sleeping, dead, last(7)}; 

TransitionProc: type = procedure [sws: Handle, state: State]; 

The TransitionProc is a client-supplied procedure responsible for allocating or deallocating 
client data structures when sws's state changes, state is the new state of sws. 

GetSleeps;: procedure[sws: Handle] returns [boolean]; 

GetSieeps returns the value of the sleeps parameter that was passed to Create when sws 
was created. If true, then the application responsible for this shell can deal with the 
sleeping state. May raise Error [notASWS]. 

GetState: procedure [sws: Handle] returns [ State ] ; 

GetState returns the current state of sws. May raise Error [notASWS]. 

GetTransitionProc: procedure [sws:Handle] returns [TransitionProc]; 

GetTransitionProc returns the current TransitionProc associated with sws. May raise 
Error [notASWS]. 

SetTransitionProc: procedure [sws: Handle, new: TransitionProc] 
RETURNS I old: TransitionProc]; 

SetTransitionProc sets the current TransitionProc for sws and returns the old one. May 
raise Error [notASWS]. 

SetState: procedure [sws: Handle, state: State] ; 

SetState sets the state of sws and calls the client's TransitionProc as appropriate. Most 
clients will not call this procedure. May raise Error [notASWS]. 

SleepOrDestroy: procedure [Handle] RETURNS[Handle]; 
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SleepOrDestroy either puts the shell in the sleeping state or destroys the shell, depending 
on the value of the sleeps boolean that was passed to Create when the shell was created. If 
the shell has the ability to sleep (sleep = true), then the shell is put into the sleeping 
state. Otherwise the shell is destroyed. The same shell is returned if the shell was put in 
the sleeping state. A nil handle is returned if the shell was destroyed. This procedure 
might be used by the desktop implementation when a shell is closed. May raise Error 
[notASWS]. 

45.2.5 Scrolling 

Usually, only part of an object is visible to the user at any one moment in the interior of a 
StarWindowShell. The user can request to see more of the object by scrolling the contents 
up or down inside the shell. The user can perform three kinds of scrolling using the 
scrollbars pictured in Figure 47.1. The contents can be moved a little at a time by pointing 
at the arrows (up, down, left, right) in the scrollbars. The contents can be moved a page or 
screenful at a time by pointing at the plus ( + ) and minus (-) signs. The user can jump to 
any arbitrary place within the entire extent of the object being viewed by pointing in the 
blank part of the vertical scrollbar (this latter operation is called thumbing). 

StarWindowShell provides various levels of support to a client for performing these 
scrolling operations. The client can allow StarWindowShell to do all the scrolling 
functions, or the client can do some of them and leave the rest to StarWindowShell, or the 
client can do all scrolling operations. Much of this decision will be based on how the client 
chooses to arrange body windows within the shell (see the section on body windows above 
and more discussion below). First, we will describe the various types of scrolling and 
scrolling procedures that a client can supply;, then we will describe the default scrolling 
procedures provided by StarWindowShell. 

In the simplest (for the client) case, one body window contains the entire extent of the 
object being viewed. StarWindowShell can handle all scrolling in this case. The client 
simply defaults the scrollData parameter in the call to StarWindowShell. Create. When the 
user points at an arrow, StarWindowShell moves the body window a small amount. When 
the user point at plus or minus, StarWindowShell moves the body window by one interior 
window's height. When the user thumbs, StarWindowShell will move the body window to 
an appropriate place based on its overall height. 

In a slightly more complex case, body windows are butted up against one another. When 
the user points at an arrow, StarWindowShell moves all the body windows a small 
amount. When the user point at plus or minus, StarWindowShell moves all the body 
windows by one interior window's height. When the user thumbs, StarWindowShell 
moves all the body windows to an appropriate place based on the combined overall height 
of the body windows. However, in this case the client will often not have the entire extent 
of the object displayed in these body windows, but rather will want to tack new body 
windows on each end as these body windows are scrolled off. The client can do this by 
providing a MoreScrollProc for the shell. StarWindowShell will call the client's 
MoreScrollProc whenever it runs out of body windows. 

In the most complex case, the client has a single body window that "just fits" (see 
SetBodyWindowJustFits in the section on body windows), and only part of the entire object 
is displayed at any one time. The client must provide all the scrolling functions for this 
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case. This means providing an ArrowScrollProc (to handle the user's pointing at the 
arrows, plus, and minus), and a ThumbScrollProc (to handle the user's thumbing). 

Of course, the client may provide its own scrolling procedures for any of the above cases, 
even the simple one, to override the type of scrolling that StarWindowShell provides. 

Scroll Data: TYPE = record [ 

displayHorizontal: boolean «- false, 
display Vertical: boolean <- false, 
arrowScroll: ArrowScrollProc <- nil, 
thumbScroll : ThumbScrollProc nil, 
moreScroll: MoreScrolllProc <- nil ]; 

ScroilData is passed to Create and SetScrollData to specify the desired scrolling. 
displayHorizontal indicates whether the shell should have a horizontal scrollbar. 
displayVertical indicates whether the shell should have a vertical scrollbar. arrowScroll is 
called when the user points at the arrows or at the plus or minus signs. thumbScroll is 
called when the user thumbs. These procedures are expected to perform the appropriate 
scroll, probably by moving body windows with window. Slide. If either arrowScroll or 
thumbScroll are nil, StarWindowShell provides default scrolling procedures 
(VanlllaArrowScroll and VanillaThumbScroll) that operate as described above, moreScroll 
is called when VanlllaArrowScroll or VanillaThumbScroll needs more body windows to be 
supplied by the client. The client should never need to supply both an arrowScroll and a 
moreScroll. 

ArrowScrollProc: type = procedure [ 
sws: Handle, 
vertical: BOOLEAN, 
flavor: ArrowFlavor, 

arrowScroll Action: ArrowScrollAction <-go]; 
ArrowFlavor: type = (pageFwd, pageBwd, forward, backward}; 

An ArrowScrollProc is called whenever the user points at an arrow or the plus or minus 
sign in a scrollbar. The ArrowScrollProc is expected to scroll the contents of sws as 
appropriate, vertical indicates whether to scroll vertically (TRUE) or horizontally (false). 
flavor indicates what type of scrolling the user requested. pageFwd means the user 
pointed at the plus sign (vertical = true) or the right margin symbol (vertical = false). 
pageBwd means the user pointed at the minus sign (vertical = true) or the left margin 
symbol (vertical = false), forward means the user pointed at the up-pointing arrow 
(vertical = true) or the left-pointing arrow (vertical = false), backward means the user 
pointed at the down-pointing arrow (vertical = true) or the right-pointing arrow (vertical 
a false). The ArrowScrollProc will be called repeatedly as long as the user has the mouse 
button down over one of the arrows, thus producing continuous scrolling. Note: 
EnumerateBodieslnlncreasingY and EnumerateBodieslnDecreasingY are quite useful 
when scrolling body windows (see the section on body windows). 

ArrowScrollAction: type = {start, go, stop}; 
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start indicates the user just buttoned down, go indicates the user still has the button 
down, stop indicates the user just buttoned up. This allows clients to scroll body windows 
without repainting until the ArrowScrollProc is called with arrowScrollAction = stop. 

ThumbScrollProc: type = procedure [ 
sws: Handle, vertical: boolean, flavor: ThumbFlavor, m, outOfN: integer]; 

ThumbFlavor: TYPE = {downClick, track, upClick}; 

A ThumbScrollProc is called whenever the user points in the thumbing part of the vertical 
scrollbar, vertical will always be true (horizontal thumbing is not currently allowed), 
flavor indicates whether the user has just buttoned down (downClick), is moving the 
mouse with the button down (track), or has just released the button (upClick). Usually, the 
actual scrolling does not take place until the upClick. downClick and track give the client 
an opportunity to display information to the user, such as what page number the current 
cursor location corresponds to (see Cursor.NumberlntoCursor). m and outOfN indicate 
where the cursor is with respect to the entire extent of the thumbing area. For example, if 
m = 200 and outOfN = 400, this indicates that the user wants to thumb to the middle of 
the entire object. Note: EnumerateBodieslnincreasingY and 
EnumerateBodieslnOecreasingY are quite useful when scrolling body windows (see the 
section on body windows). 

MoreScrollProc: type = procedure [ 
sws: Handle, vertical: boolean, flavor: MoreFlavor, amount: cardinal]; 

MoreFlavor: type = {before, after}; 

A MoreScrollProc is called by the default StarWindowShell scrolling procedures, 
VanillaArrowScroll and VanillaThumbScroll, whenever more body windows are needed to 
continue scrolling. This is used when the client has several body windows butted against 
one another. When the user points at an arrow, VanillaArrowScroll moves all the body 
windows a small amount. When the user point at plus or minus, VanillaArrowScroll moves 
all the body windows by one interior window's height. When the user thumbs, 
Vanillalh umbScroll will move all the body windows to an appropriate place based on the 
combined overall height of the body windows. However, the client will often not have the 
entire extent of the object displayed in these body windows, but rather will want to tack on 
new body windows on each end as these body windows are scrolled off. This is when the 
client's MoreScrollProc is called, vertical indicates whether the user was scrolling 
vertically or horizontally, flavor indicates whether to tack on more body windows before 
(i.e., user was scrolling down for vertical = true, right for vertical = false), or after (i.e., 
user was scrolling up for vertical « true, left for vertical = false), amount indicates how 
much extra body window is needed, in screen dots. 

The client's moreScroll procedure is responsible for adding and deleting body windows 
from the shell. The case being handled is that in which the client has a large number of 
pages to display to the user and wishes to only manifest a few. Then we need to handle the 
case in which system scrolling would make a non-manifest page visible, and there is no 
body window for it. Whenever the system is about to perform a scroll function, it checks to 
see if the scroll action would move the visible portion of the bodies off the end of the 
existent body windows. If so, it calls a non-nil client MoreScrollProc, indicating how much 
more body window may be displayed. The client may augment the collection of body 
windows or not. The system routines will not scroll past the end of the body windows. The 
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client may also use this opportunity to garbage-collect body windows that have been 
scrolled off the other end and are no longer visible. 

noScrollData: ScrollData <-[]; 

noScrollOata indicates no scrollbars at all. 

vaniilaScroliData: ScrollData <— [ 
dispiayHorizontal: false, 
displayVertical: true, 

arrowScroll: nil, -- actua//y VanillaArrowScroll 
thumbScroll: nil,-- actua//y VanillaThumbScroll 
moreScroll: nil]; 

vaniilaScroliData is the default for the scrollData parameter to Create. It indicates vertical 
scrollbar with the StarWindowShell.VanlllaXXXScroll procedures described above. 

GetScrollData: procedure (sws: Handle] returns [scrollData: ScrollData]; 

GetScrollData returns the current ScrollData associated with sws. May raise Error 
[notASWS]. 

SetScrollData: procedure [sws: Handle, new: ScrollData] 
returns [old: ScrollData]; 

SetScrollData sets the current ScrollData for s\ns and returns the previous. May raise 
Error [notASWS]. 

Van i I la ArrowScrol I : ArrowScroHProc; 
VanillaThumbScroll: ThumbScrollProc; 

The default scrolling procedures provided by StarWindowShell are exported here. This 
allows a client to insert its own scroll procedures, check for certain conditions that the 
client wants to handle, and call StarWindowShell to do the scrolling for other conditions. 



45.2.6 Push, Pop, etc. 

The StarWindowShell returned by Create is not displayed on the screen; i.e, is not inserted 
into the visible window tree. A StarWindowShell may be inserted into the window tree by 
calling Push. This is usually not done by the client, but rather by some other part of 
ViewPoint,, such as the desktop implementation. For example, when the user selects an 
icon and presses OPEN or PROPS, the application (actually the application's 
Containee.GenericProc) creates a StarWindowShell and returns it. The desktop 
implementation then displays the StarWindowShell by doing a Push. 

A StarWindowShell is removed from the screen by calling Pop. Clients will almost never 
call Pop. Rather, StarWindowShell calls Pop when the user selects Close, or 
PropertySheet calls Pop when the user selects Done or Cancel. 

Push allows one shell to be pushed on top of another shell, thus providing the illusion of 
"open-within." For example. Star folders and file drawers make heavy use of this illusion. 
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StarWindowShell has provisions for a shell to display commands in the header of the 
shells pushed on top of it. (See the Pushee Commands section.) Most clients will not make 
use of this feature of Push, since the ContainerWindow interface takes care of this for 
applications that appear as a list of items that may be opened. Fine Point: We simplify things! 
here by replacing the entire shell. When the shell on top is closed, the shell below still exists and is simply 
redisplayed. 

Push: PROCEDURE [ 

newShell: Handle, topOf Stack: Handle nil, 
poppedProc: PoppedProc «e-NiL]; 

Push displays newShell by inserting it into the visible window tree. If topOf Stack is nil,, 
newShell is placed directly on the desktop. If topOf Stack is not nil, then newShell is 
pushed on top of topOfStack and topOf Stack is removed from the display (but see the fine 
point below). If topOfStack is not nil, it must be currently visible, i.e,. does not have 
another shell Pushed on top of it. If poppedProc is not nil, it is called when newShell is 
Popped. The poppedProc must either sleep the shell or destroy the shell, usually by 
calling SleepOrDestroy. If poppedProc is nil, newShell will be destroyed when it is 
Popped. Note that Push can be called repeatedly with topOfStack being the newShell from 
the previous call, thus producing a stack of StarWindowShells. May raise Error 
[notASWS]. 

Fine point: For open-within, we are experimenting with opening the newShell overlapping the topOfStack shell,, 
allowing the user to look at the container and the thing contained at the same time. This has some rather complex 
implications with respect to having two views of the same things, being able to open several contained items at 
once, etc. 

PushedMe: procedure [pushee: Handle] 
RETURNS [pusher: Handle]; 

PushedMe returns the next lower shell below pushee in the stack (nil if none). Fine Point: 

This procedure is currently exported through StarWindowShellExtra. 

PushedOnMe: procedure [pusher: Handle] 
RETURNS [pushee: Handle]; 

This procedure returns the next higher shell above pusher in the stack (nil if none) Note: 

This procedure is currently exported through StarWindowShellExtra. 

PoppedProc: type = procedure [popped, newShell: Handle, 
popOrSwap: PopOrSwap <- pop]; 

PopOrSwap: TYPE a {pop, swap}; 

popped is the shell that is being taken out of the visible window tree. newShell is the shell 
that will become visible because of popped being popped. This will be nil if popped was 
not opened within another window. popOrSwap indicates the action that caused the shell 
to be popped, either StarWindowShell. Pop or StarWindowShell. Swap. 



Pop: PROCEDURE [popee: Handle] returns [Handle]; 




Pop removes popee from a stack of shells and returns the shell that is now on top of the 
stack. If popee was Pushed with a poppedProc, this poppedProc is called. If popee is not 
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the top of a stack, then all shells above it in the stack are Popped. May raise Error 
[notASWS]. 

Swap: PROCEDURE [ 

new, old: Handle, 

poppedProc: PoppedProc <r- nil] ; 

Swap replaces old, which must be the top of a stack, with new. Equivalent to a Pop 
followed by a Push, but with a lot less screen flashing. May raise Error [notASWS]. 

Replace: procedure [new, old: Handle]; 

Replaces the old shell with new without calling old's PoppedProc. old's PoppedProc 

becomes the PoppedProc for new. Fine Point: This procedure is currently exported through 
StarWindowShellExtra. 

45.2.7 Limit and Adjust Procs 

Limit and Adjust procs are client-supplied procedures that allow a client to get control 
whenever a StarWindowShell is going to change size or location. A LimitProc gives the 
client control over the size and placement of a shell. An AdjustProc gives the client an 
opportunity to fix up the data structures and display for the shell's body window(s). 

LimitProc: type = procedure [sws: Handle, box: window.Box] returns [window. Box]; 

GetLimitProc: procedure [sws: Handle] returns [LimitProc]; 

SetLimitProc: procedure [sws: Handle, proc: LimitProc] RETURNS [old: LimitProc]; 

Whenever the size or location of a shell is going to change, the client's LimitProc is called. 
This allows the client to exercise veto or modification rights over the size and location of a 
StarWindowShell. This is useful, for example, to prohibit a shell from becoming smaller 
than some certain size or being moved completely off the screen, box is the requested size 
of the shell. The LimitProc should return the desired size of the shell. The LimitProc is 
called before the AdjustProc. The interior box of the shell box returned by the LimitProc is 
passed to the AdjustProc. GetLimitProc and SetLimitProc may raise Error [notASWS]. 

StandardLimitProc: LimitProc; 

A StandardLimitProc is provided that keeps shells on the screen and keeps them from 
getting too small. 

AdjustProc: type = procedure [sws: Handle, box: window.Box, when: When]; 
When: type = {before, after}; 

GetAdjustF>roc: procedure [sws: Handle] returns [AdjustProc]; 

SetAdjustProc: procedure [sws: Handle, proc: AdjustProc] RETURNS [old: AdjustProc]; 

The AdjustProc will be called whenever the shell is going to change size. It is called both 
before and after the window's size is changed. The box passed to the AdjustProc is the 
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interior window's box (the client's viewing region in the shell). The when parameter 
indicates whether the current call is before or after the window's size has been changed. | 
An AdjustProc is for those clients whose body window display depends on the size of the 
surrounding shell. For example, if the body window sticks out of the interior of the shell 
and the user must scroll the body window horizontally to see all the contents, then no 
AdjustProc is needed. If, on the other hand, the content of the body window is always kept 
visible regardless of the size of the shell (by wrapping the contents around as in the Tajo 
FileWindow editor), then the client will need an AdjustProc. GetAdjustProc and 
SetAdjustProc may raise Error [notASWS]. 

45.2.8 Displayed StarWindowShells 

EnumerateDispiayed: procedure [proc: ShellEnumProc] returns [Handle <-(nil]]; 

EnumerateDisplayedOfType: procedure [ShellType, proc: ShellEnumProc] 
RETURNS [Handle <- [nil]]; 

EnumerateMyDisplayedParasites: [sws: Handle, proc: ShellEnumProc] 
RETURNS [Handle <- [NIL]]; 

ShellEnumProc: TYPE = procedure [victim: Window. Handle] 

RETURNS [stop: BOOLEAN <- FALSE]; 

These procedures enumerate visible StarWindowShells. Each one returns the last shell 
incurred in the enumeration if the ShellEnumProc returns true, otherwise they return nil. ^iftl^ 
EnumerateMyDisplayedParasites may raise Error [notASWS]. 

45.2.9 Errors 

Error: ERROR[code: ErrorCode]; 

ErrorCode: type « {desktopNotUp, notASWS, notStarStyle,tooManyWindows}; 

45.3 Usage/Examples 

Create a StarWindowShell 



CreateShell: procedure returns [starwindowSheii.Handle] s { 

another: xstring.ReaderBody xstring.FromSTRING["Another"L]; 
repaint: xstring.ReaderBody «- xstring.FromSTRING["Repaint"L]; 
post: xstring.ReaderBody *-xstring.FromSTRING["Post A Message"L]; 
sampleTool: xstring.ReaderBody <-xstring.FromSTRING["Sample Toor'L]; 

— Create the StarWindowShell 

shell: StarwindowSheii.Handle = starwindowSheii.Create [name: ©sampleTool]; 

— Create a body window inside the StarWindowShell 
body: window. Handle » StarWindowShell. CreateBody [ 

sws: shell. 
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box: [ [0,0], bodyWindowDims ], 
repaintProc: Redisplay, 
bodyNotifyProc: Notify Proc ]; 

— Create some menu items 

z: UNCOUNTED ZONE *-starwindowSheii.GetZone [sliell]; 

items: array [0..3) of MenuOata.ltemHandle «- [ 

MenuData.Createltem [zone: z, name: ©another, proc: MenuProc], 
MenuData.Createltem [zone: z, name: ©repaint, proc: RepaintMenuProc], 
MenuData.Createltem [zone: z, name: ©post, proc: Post] ]; 

myMenu: MenuData.MenuHandle s MenuOata.CreateMenu [ 
zone: z, 
title: NIL, 

array: descriptor [items]]; 
starWindowSheil.SetRegularCommands [sws: shell, commands: myMenu]; 



RETURN [shell]; 
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Item 


Page 
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AddPopupMenu:PROCEDURE 


12 


MenuEnumProc: type 


13 


AdjustProc: type 


21 


MoreFlavor: type 


18 


ArrowFlavor: type 


17 


MoreScrollProc: type 


18 


ArrowScroll Action: type 


17 


NewStandardCloseEverything: procedure 


7 


ArrowScrollProc: type 


17 


noScrollData: Scroll Data 


19 


BodyEnumProc: type 


11 


nuilHandle: Handle 


6 


Create: procedure 


4 


Pop: PROCEDURE 


20 


CreateBody: procedure 


10 


PopOrSwap:TYPE 


20 


DestailBody: procedure 


11 


PoppedProc: type 


21 


Destroy: procedure 


6 


Push: PROCEDURE 


20 


Destroy Body: procedure 


10 


PushedMe: procedure 


20 


EnumerateAliMenus: procedure 


13 


PushedOnMe: procedure 


20 


EnumerateBodieslnDecreasingY: procedure 


10 


Replace: procedure 


21 


EnumerateBodieslnlncreasingY: procedure 


10 


Scroll Data: type 


17 


EnumerateDisplayed: procedure 


22 


SetAdjustProc: procedure 


21 


EnumerateDispiayedOfType: procedure 


22 


SetBodyWindowJustFits: procedure 


11 


EnumerateMyDisplayedParasites: procedure 


22 


SetBottomPusheeCommands: procedure 


14 


EnumeratePopupMenus: procedure 


13 


SetContainee 


9 


Error: error 


22 


SetCurrentlyShowingCoverSheet: procedure 


21 


ErrorCode: type 


22 


SetHost: procedure 


9 


GetAdjustProc: procedure 


21 


SetlsCloseLegalProc: procedure 


8^ 


GetAvailableBodyWindowDims: procedure 


11 


SetLimitProc: procedure 


21 


GetBody: procedure 


10 


SetMiddlePusheeCommands : procedure 


14 


GetBodyWindowJustFits: procedure 


11 


SetName: procedure 


9 


GetContainee: procedure 


8 


SetNamePicture: procedure 


9 


GetHost: procedure 


8 


SetPreferredDims: procedure 


7 


GetlsCloseLegalProc: procedure 


8 


SetPreferredlnteriorDims: procedure 


7 


GetLimitProc: procedure 


21 


SetPreferredPlace: procedure 


7 


GetPusheeCommands: procedure 


14 


SetReadOnly: procedure 


9 


GetReadonly: procedure 


8 


SetRegularCommands: procedure 


12 


GetRegularCommands: procedure 


12 


SetScrollData: procedure 


19 


GetScrollData: procedure 


19 


SetSleeps: procedure 


9 


GetSieeps: procedure 


14 


SetState: procedure 


15 


GetState: procedure 


14 


SetTopPusheeCommands: procedure 


14 


GetTransitionProc: procedure 


14 


SetTransitionProc: procedure 


15 


GetType: procedure 


8 


ShellEnumProc: type 


22 


GetZone: procedure 


8 


ShellFromChild: procedure 


10 


Handle: type 


6 


ShellType: type 


6 


HaveDisplayedParasite: procedure 


8 


SleepOrDestroy: procedure 


16 


InstallBody: procedure 


11 


StandardClose: procedure 


7 


IsBodyWindowOutOf Interior: procedure 


11 


StandardCloseAII: procedure 


7 


IsCioseLegal: procedure 


8 


StandardCloseEverything: procedure 


7 


IsCloseLegalProc: type 


6 


StandardLimitProc: LimitProc 


21 


IsCloseLegalProcReturnsFalse: procedure 


8 


State: type 


14 


LimitProc: type 


21 


SubtractPopupMenu: procedure 


13^ 
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Swap: PROCEDURE 21 

ThumbFlavor: type 18 

ThumbScrollProc: TYPE 18 

TransitionProc: TYPE 14 

UseMyCoverSheetProc: procedure 21 

VanillaArrowScroll: ArrowScrollProc 19 

vanillaScrollData: ScrollData 19 

VanillaThumbScroll: ThumbScrollProc 19 

When: TYPE 21 
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46.1 Overview 

TIP provides basic user input facilities through a flexible mechanism that translates 
hardware- level actions from the keyboard and mouse into higher-level client action 
requests (result lists). The acronym TIP stands for terminal interface package. This 
interface also provides the client with routines that manage the input focus, the periodic 
notifier, and the STOP key. 

46.1.1 Basic Notification Mechanism 

The basic notification mechanism directs user input to one of many windows in the 
window tree. Each window has a Table and a NotifyProc, The table is a structure that 
translates a sequence of user actions into a sequence of results that are then passed to the 
notify procedure of the window. 

There are two processes that share the notification responsibilities, the Stimulus process 
and the Notifier process. The Stimulus process is a high-priority process that wakes up 
approximately 50 times a second. When it runs, it makes the cursor follow the mouse and 
watches for keyboard keys going up or down, mouse motion, and mouse buttons going up 
or down, enqueuing these events for the Notifier process. 

The Notifier process dequeues these events, determines which window the event is for, 
and tries to match the events in the window's table. If it finds a match in the table, it calls 
the windov/s notify procedure with the results specified in the table. If no match is found, 
it tries the next table in the window's chain of tables. If no match is found in any table, the 
event is discarded. 

The Notifier process is an important process. To avoid multi-process interference, some 
operations in the system are restricted to happen only in the Notifier process. Setting the 
selection is one such operation. The Notifier process is also the one most closely tied to the 
user. If an operation will take an extended time to complete, it should be forked from the 
notifier process to run in a separate process so that the Notifier process is free to respond to 
the user's actions. 
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46.1.2 Tables 

Tables provide a flexible method of translating user actions into higher-level client- 
defined actions. They are essentially large select statements in which the user's actions 
are matched against the left side of a table with a corresponding set of results on the right 
side. Left sides of tables specify triggers-changes in state of keys~and ena6/ers-existing 
state of keys— to be matched with the user actions. Right sides of tables specify results that 
include mouse coordinates, atoms, and strings for keyboard character input. A complete 
syntax and semantics of tables are in § 46.3.2 and §46.3.3. 

Tables have a user-editable filed representation that is parsed to build a runtime data 
structure for TIP. The user-editable filed representation must be in the system catalog and 
is assumed to have a file name extension of .TIP. When a table is created by calling the 
Create Table operation, the tip file is parsed and its runtime data structure is created. In 
addition, a compiled version of the tip file is created in a file whose name has the character 
C appended to the name of the tip file. On subsequent calls to CreateTable, this tipc file is 
used to create the runtime data structure as long as the tip file has not been changed. By 
avoiding parsing the tip file, building the runtime data structure from the compiled file is 
much faster. 

The table parser uses a macro package that allows macros to be defined and used in 
writing tables. It is described in §46.3.7. 

Tables may be linked to form a chain of tables. The notifier process attempts to match user 
actions in the first table of the chain. If no match is found, it tries subsequent tables in the 
chain. If no match is found in any table, the user action is discarded. Clients can use the 
links of tables to build special processing on top of basic facilities. The client can write its 
own table to handle special user actions and, by linking the table to system-defined tables, 
let them handle the normal user actions. An example is in the Usage/Examples section. 
System-defined tables, which are accessable through the TIPStar interface, are described 
in Appendix A. 

46.1.3 Input Focus 

The input focus is a distinguished window that is the destination of most user actions. 
User actions may be directed either to the window with the cursor or to the input focus. 
Actions such as mouse buttons are typically sent to the window with the cursor. Most 
other actions, such as keystrokes, are usually sent to the current input focus. 

The notifier process uses either the input focus window or the cursor window to obtain a 
table and a notify procedure. Results from matching the user actions with the table are 
normally passed to the window's notify procedure. Notify procedures may also be bound 
directly with a table. In this case, results from the table go to the table's notify procedure 
instead of to the window's notify procedure. 

Clients may make a window be the current input focus and be notified when some other 
window becomes the current input focus. 
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46.1.4 Periodic Notification 

The Notifier process is important because it responds directly to the user. To avoid multi- 
process interference, some operations in the system are restricted to happen only in the 
Notifier process. The periodic notification mechanism allows operations to happen within 
the Notifier process while the user is idle. A periodic notifier is created with a window, 
some results, and a time interval. The window's notify procedure is called with the results 
every time interval as long as the Notifier process is not processing user actions. 



46.1.5 Call-Back Notification and Setting the Manager 

Call-back notification and setting of the manager bypass the normal means of selecting a 
window as the destination of input and allow the client to receive all input. It is useful for 
something like mouse tracking when a menu is posted. This must be done only from the 
Notifier process. 

Call-back notification is so named because the client calls back to the Notifier process with 
a special call-back notification procedure, a window and a table. The Notifier matches user 
actions with the table and sends the results to the call-back notify procedure. It continues 
to do this until the call-back notify procedure says it is done. User actions that are not 
matched are discarded. 



Setting the manager makes the Notifier process use the manager's table for matching user 
actions and send the results to the manager's notify procedure. User actions that are not 
matched are discarded. 

While both call-back notification and setting the manager results in ail notifications being 
sent to a single place, they are different in the control structure. With call-back 
notification, the client's call stack is not unwound, while setting the manager does not 
take effect until the current notification is processed and its call stack unwound. 



46.1.6 Attention and User Abort 



While most notifications are sent to notify procedures from the notifier process, there is a 
mechanism that allows asynchronous notification of the STOP key. An AttentionProc may 
be set for a window that is called whenever the STOP key is depressed in that window. It is 
called from outside the notifier process as soon as the stimulus level sees the key go down. 
For those windows that do not set an AttentionProc, the system keeps a user abort Hag 
that records whether the STOP key was depressed. Clients may call UserAbort to check if 
the flag is set. It is cleared when any notification is sent to the window's notify procedure. 



46.1.7 Stuffing Input into a Window 



TIP provides operations that allow a client program to call the notify procedure of a 
window with results that the client constructs. StuffResults allows a client to pass an 
arbitrary results list to a window. StuffString, StuffSTRING, and StuffCharacter allow 
strings and characters to be passed to a window. 



46-3 



46 TIP 



46.2 Interface Items 

46.2.1 Results 

Results: TYPE = long pointer to ResultObject; 

ResultObject: type = record [ 
next: Results, 
body: select type: *from 

atom a > [a: ATOM], 

bufferedChar = > null, 

coords a > [place: Window. Place], 

int = > [1: long integer], 

key = > [key: KeyName, downUp: DownUp], 

nop 3 > [], 

string s > [rb: xstring.ReaderBody], 
time = > [time: System. Pulses], 
endcase]; 

ATOM: TYPE a Atom.ATOM; 

DownUp: TYPE ■ LeveliVKeys.DownUp; -- {down, up} 
KeyName: type a LeveiiVKeys.KeyName; 

The right side of a statement in a table is a list of results to be passed to the notify 
procedure when there is a match on the left side. Each element of this list of results is 
described by a ResultObject. The atom variant contains the atom from the table's right 
side. The place in the coords variant is relative to the window receiving the results. The 
reader body of the string variant is either from the bufferedChar results or from a string 
constant in the table. The pulses of the time variant is the value of System. GetPulses at 
the time the event actually occurred. 

Character input is buffered by the Notifier process. If the result of a match is a 
bufferedChar, the Notifier process buffers the character and proceeds to try and match the 
next user actions. If there are no more user actions and the buffer of character input is not 
empty, the Notifier process calls the notify procedure with the buffered character input. If 
the next action produces a result that is not another character input, the Notifier process 
calls the notify procedure with the buffered character input and then call it with the new 
result. If the notifier process gets behind the user and a lot of character input actions get 
queued up, it collects them and passes them together to the client instead of one at at time. 

KeyName is an enumerated that describes the keyboard and mouse buttons. See §5.2 in 
the Pilot Programmer's Manual (610E00160) for a complete list of the elements. 

46.2.2 Notify Procedure 

NotifyProc: type ■ procedure [window: window.Handle, results: Results]; 

A NotifyProc is the means of notifying a window of user input. The parameters are the 
window that is receiving the input and the list of results that describe the input. 
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Normally, the results are from the tip table associated with the window. Notify procedures 
may also be bound directly with a table. In this case, results from the table go to the table's 
notify procedure instead of to the window's notify procedure. 

46.2.3 TIP Tables 

Table: TYPE = long pointer to TableObject; 
TableObject: type; 

Table is a pointer to the internal representation of a table. 
GetTableLink: procedure (from: Table] returns fto: Table]; 
SetTableLink: procedure [from, to: Table] returns [old: Table]; 

GetTableLink and SetTableLink allow the tables to be linked. GetTableLink returns the 
table following from in the chain, returning nil if there is no successor table. SetTableLink 
sets the link of table from to to and returns the old value. 

SetTabieOpacity: procedure [table: Table, opaque: boolean] 
returns [oidOpaque: boolean]; 

GetTableOpacity: procedure [table: Table] returns [boolean]; 

SetTabieOpacity sets the opacity of table and returns the old value, while 
GetTableOpacity returns its value. If a table is opaque, then unrecognized user actions are 
discarded without searching the table chain past the opaque entry. 

46.2.4 Associating Notify Procedures, Tables, and Windows 

SetTableAndNotifyProc: procedure [ 

window: window.Handle, table: Table <- nil, notify: NotifyProc nil]; 

SetTableAndNotifyProc makes window a TIP client and associates the table and notify 
procedure with the window. If window is already a TIP client and table or notify is nil, 
then the old value is retained. 

SetTable: procedure [window: window.Handle, table: Table] returns [oldTable: Table]; 
GetTable: procedure [window: window.Handle] returns [Table]; 

SetTable sets the table associated with window to be table and returns the old table. 
GetTable returns the table associated with window. 

SetNotifyProc: procedure [window: window.Handle, notify: NotifyProc] 
returns [oldNotify:NotlfyProc]; 

GetNotifyProc: procedure [window: window.Handle] returns [NotifyProc]; 
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SetNotifyProc sets the notify procedure associated with window to be notify and returns 
the old notify procedure. GetNotifyProc returns the notify procedure associated with 
window. 

SetNotifyProcForTable: procedure [table: Table, notify: NotifyProc] 
RETURNS [oldNotify: NotifyProc]; 

GetNotifyProcFromTable: procedure [table: Table] returns [NotifyProc]; 

SetNotifyProcForTable binds the notify procedure, notify, with table and returns the old 
value of bound notify procedure. Results from matches within the table will go to notify 
instead of to the notify procedure for the window this table is associated with. 
GetNotifyProcFromTable returns the notify procedure bound to table. 

46.2.5 Creating and Destroying Tables 

CreateTable: procedure [ 

file: xstring.Reader, z: uncounted zone <- nil, contents: xstring.Reader nil] 
returns [table: Table]; 

CreateTable generates a TIP table from the text file named by file (which may not be nil). 
Storage for the table will be allocated in z or from the implementation's zone if z is nil. 
contents is the default contents of file, and will be used if (1) the 'I boot switch is set, (2) 
the file cannot be read, or (3) the signal InvalidTable is resumed. (See InvalidTable for 
further details on how to treat that SIGNAL.) 

When file is parsed, a compiled form of the table is written into a file with a name 
constructed by appending a C on the end of file. Fine Point: file should typically have the extension 

.TIP. When CreateTable is called, if a .TIPC file exists that was created from file, the .TIPC 
file is used to generate table. 

This procedure may raise the signal InvalidTable. 

CreateCharTable: procedure [ 

z: uncounted zone <- nil, buffered: boolean true] returns [table: Table]; 

CreateCharTable creates a TIP table such that any down transition of any of the 
keystations (not key tops) in the main typing array have a right-hand side of bufferedchar. 
Storage is allocated from z if it is non-NiL or from the TIP implementation's zone. The 
boolean buffered is ignored and will be removed when this interface is updated. 

CreatePlaceHolderTable: procedure [z: uncounted zone <- nil] returns [table: Table]; 

CreatePlaceHolderTable creates a placeholder tip table. Placeholder tables contain no 
information themselves but allow other tables with information to be linked to them. 
Storage is allocated from z if it is non-NiL or from the TIP implementation's private zone. 

DestroyTable: procedure [long pointer to Table]; 

DestroyTable frees the table addressed by the parameter and then sets the table to nil. 
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46.2.6 Input Focus 

SetlnputFocus: proc[ 

w: window.Handie, takeslnput: boolean, newlnputFocus: LosingFocusProc<T"NiL, 
clientData: long pointer «- nil]; 

SetlnputFocus makes the window w the input focus. If w allows type-in, takeslnput should 
be set to true; otherwise takeslnput should be set to false. newlnputFocus is called when w 
loses the input focus. It is passed clientData as the value of its long pointer parameter. 

LosingFocusProc: type = procedure [w: Window. Handle, data: long pointer]; 

LosingFocusProc describes the procedure type that is used to let the input focus know it is 
no longer the input focus, w is the Window. Handle of the window that was the input focus, 
and data is the client data passed to SetlnputFocus. 

GetlnputFocus: proc returns [window. Handle]; 

GetlnputFocus returns the window that currently has the input focus. 
backStoplnputFocus: readonly window. Handle; 

The window backStoplnputFocus gets all input focus notification when no other window 
requests to be the input focus. It may be nil. 

SetBackStoplnputFocus: procedure [window: window.Handle]; 

SetBackStoplnputFocus sets backStoplnputFocus, the window that gets all input focus 
notification if no other window requests to be the input focus. 

FocusTakeslnput: proc returns [boolean]; 

FocusTakeslnput returns true if the current input focus accepts input, false otherwise. 
ClearinputFocusOnMatch: proc[w: window.Handle]; 

ClearlnputFocusOnMatch is used to clear the input focus in a window if that window has 
the input focus. This procedure is usually called by clients who are implementing their 
own window type when they are destroying a window. 

46.2.7 Character Translation 

CharTranslator: type ■ record [ 

proc: KeyToCharProc, data: long pointer]; 

KeyToCharProc: type = procedure [ 

keys: long pointer to KeyBits, key: KeyName, downUp: OownUp, data: long pointer, 
buffer:xstring.Writer]; 

A CharTranslator is used to construct characters from the state of the keyboard when a 
bufferedchar result is encountered. The KeyToCharProc is called when the notifier needs 
to construct a character from the state of the keyboard, keys describes the current state of 
the keyboard, key and downUp describe the current character transition. The procedure 
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should append the corresponding character(s) to buffer. There is a CharTranslator for each 
table. 

KeyBits: type a LeveiivKeys. Key Bits ; 

SetCharTranslator: procedure [table: Table, new: CharTranslator] 
RETURNS [old: CharTranslator]; 

GetCharTranslator: proc [table: Table] returns [o: CharTranslator]; 

SetCharTranslator sets the character translator for table, returning the old value. 
GetCharTranslator returns the character translator for table. 



46.2.8 Periodic Notification 

PeriodicNotify: type [1]; 
nullPeriodicNotIfy: PeriodicNotify; 

PeriodicNotify is a handle for a periodic notifier. Periodic notifiers are a means of 
notifying windows at regular intervals from within the Notifier. nullPeriodicNotify is the 
null value for PeriodicNotify. 

CreatePeriodicNotify: proc [ 

window: window.Handle, results: Results, milliseconds: cardinal, 
notifyProc: NotifyProc<-NiL] 
returns [PeriodicNotify]; 

CreatePeriodicNotify registers a periodic notification. If notifyProc = nil then the notify 
proc associated with window is used. If notifyProc # nil, is called; this is useful if the client 
is running in a background process but wants to perform some operation that must be 
done in the notifier process, such as obtaining the current selection. If there is a COORDS 
result and window a nil , that result is [0, 0]. If notifyProc = nil and window = nil , the 
Error[other] is raised. The specified notify proc is called with parameters window and 
results once every milliseconds milliseconds as long as no user action notifications are 
taking place. If milliseconds = 0, it runs once and then destroys itself. The result list 
should not contain any entries of type nop or bufferredChar. Right-hand sides of type 
coords will be adjusted to reflect the actual mouse position relative to the window being 
notified. The results list will not be copied. Its allocation is up to the client. 

CancelPeriodicNotify: proc [ 

PeriodicNotify] returns [null: PeriodicNotify]; 

CancelPeriodicNotify stops the periodic notification passed in by removing the notification 
from the list of registered procedures and returns nullPeriodicNotify. This procedure 
raises Error[noSuchPeriodicNotifier] if the handle passed in is not valid (calling it with 
nullPeriodicNotify has no effect). 

46.2.9 Call-Back Notification 

CaliBack: procedure [window: window.Handle, table: Table, notify: CallBackNotifyProc]; 
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CaliBackNotifyProc: type a procedure [window: window.Handle, results: Results] 
RETURNS [done: boolean]; 

Call-back notification allows the client to receive all input. It is useful for something like 
mouse tracking when a menu is posted. CallBack uses table to match all user input and 
calls notify for each successful match in the table with window and the results from the 
table as parameters. CallBack will continue to send all notifications to notify as long as 
notify returns done: false. Call-back notification is similar to setting the Manager except 
that the client's call stack is not unwound. User actions that are not matched are 
discarded. 

46.2.10 Manager 

Manager: type « record [ 

table: Table, window: wiindow.Handle, notify: NotifyProc]; 

nullManager: Manager = [nil. trash, trash]; 

Manager is used to send all user actions through table and notify, using window instead 
of through the window, table, and notify procedure determined by actionToWindow and 
TIPs Match process. If table is nil, as in nullManager, then the standard mechanisms will 
be used to determine where actions will be sent. 

GetManager: proc returns [current: Manager]; 

GetManager returns the current manager. 

ClearManager: procedure s inline . . .; 

ClearManager sets the manager to nullManager. It should only be called by clients who 
know that they set the manager from null to non-null. 

SetManager: procedure [new: Manager] returns [old: Manager]; 

SetManager does the obvious thing. 



46.2,11 User Abort 

UserAbort: proc [window.Handle] returns [boolean]; 

UserAbort returns whether the user abort flag is set for the window. The bit may be set by 
calling SetUserAbort or by the system if the window does not have an attention procedure 
and the stop key is depressed in that window. If window is nil, the Userlnput package 
checks to see whether the user has done a global abort. When a non-shift key goes down, 
this flag and the global abort flag are cleared. 

ResetUserAbort: proc [window.Handle]; 

ResetUser Abort sets user abort flag for the window to false. 

SetUserAbort: proc [window.Handle] 
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SetUserAbort sets the user abort flag for the window. This does not call the window's 
attention procedure, if there is one. 



AttentionProc: TYPE = proc [window: window.Handle]; 

An AttentionProc is a procedure called whenever the STOP key is depressed. It is called 
from a high-priority process— not the Notifier— as soon as the stimulus level sees the key 
go down. 

SetAttention: proc [window.Handle, attention: AttentionProc] 

SetAttention sets the attention procedure for the window. The procedure attention is 
called asynchronously >Vhenever the STOP key is depressed. 



StuffCharacter: proc [ 

window: window.Handle, char: xstring.Character] returns [boolean] 

StuffCharacter allows a client to drive the type-in mechanism as though a character were 
coming from the user. The notify procedure of window is called with a string result that 
contains char. The returned boolean is true only if window was prepared to accept input. 

StuffCurrentSelection: proc [window: window.Handle] returns [boolean] 

StuffCurrentSelection allows a client to drive the type-in mechanism as though the 
contents of the current selection were coming from the user. The selection is converted to a 
string and the string is passed to the window's notify proc. (See the Selection interface for 
a description of the current selection.) The returned boolean is true only if window was 
prepared to accept input. 

StuffResults: procedure [window: window.Handle, results: Results]; 
Stuff Results calls the notify proc of window with results. 

StuffString: proc [window: window.Handle, string: xstring.Reader] returns [boolean] 

Stuff String allows a client to drive the type-in mechanism as though string were coming 
from the user. The notify procedure of window is called with a string result that contains 
string f . The returned BOOLEAN is true only if window was prepared to accept input. 

StuffSTRING: procedure [window: window.Handle, string: long string] 

RETURNS [BOOLEAN]; 

Stuff STRING calls the notify procedure of window with a results list that contains a string 
ResultObject whose reader body describes the characters in string. 

StuffTrashBin: proc [window: window.Handle] returns [boolean] 



StuffTrashBin is currently not implemented. 





46.2.12 Attention 



46.2.13 Stuffing Input into a Windov^^ 
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46.2.14 Errors 

invalidTable: signal [type: TabieError, message: xstring.Reader]; 
TableError: type » {lileNotFound, badSyntax};. 

InvalidTable is only raised by CreateTable. The type is fileNotFound if the file could not be 
found and the message string was empty. fileNotFound is raised as an ERROR . The type is 
badSyntax if the current file is syntactically incorrect. If badSyntax is RESUMEd, and 
message is not empty, the message is written into file, and it is reparsed. If the file has 
been overv/ritten, or message is empty, and there is a syntax error, the error will be 
badSyntax. In this case if the signal is resumed, CreateTable simply returns nil. 

Error: error [code: ErrorCode]; 

ErrorCode: type = {noSuchPerlodicNotifier, other}; 

ReturnToNotifier: error [string: xstrlng.Readerl; 

Sometimes a client is deep in the call stack of some Notifier-invoked operation from which 
it wishes to unwind. The ERROR ReturnToNotifier can be raised and will be caught at the 
top level of the Notifier process. Clients can catch this error, post a message with string in 
it, and let the error propagate up. 



46.2.15 Miscellaneous Items 

GetPlace: procedure [window: window. Handle] returns [window.Place]; 

GetPlace returns the window relative coordinate of the last user action that was matched. 
GetPlace should only be invoked while in the notifier process. 

actionToWindow: packed array KeyName of boolean; 

actionToWindow determines if a user action should be sent to the window containing the 
cursor (true) or to the window containing the current input focus (false). This array is 
global to the entire environment. It is initialized to have all actions go to the input focus, 
except those associated with the Adjust, Menu, and Point mouse buttons and the stop key. 

caretRate: Process.Ticks, 

clickTimeout: System. Pulses; 

clickTimeout and caretRate are values that are set by user profile. Clients who implement 
blinking carets may use caretRate to determing the rate of caret blinking. Clients who 
implement click timeout without using the timing facilities in tables may use 
clickTimeout to determine the maximum time allowed between two clicks of a multi-click. 

FiushUserlnput: procedure; 

FlushUserlnput empties the queue of pending user actions (type- ahead and button- 
ahead). 
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46.3 Usage/Examples 

46.3.1 Periodic Notification 

The following example shows the use of a periodic notifier for updating a display of the 
volume page count. The page count will be updated every 20 seconds, provided that the 
Notifier is not otherwise occupied. 

window: window.Handle ^h- 

updateCount: Atom.ATOM <-Atom.MakeAtom("UpdateCount"L]; 
results: ResultsObject «-[next: nil, body: atom[a: updateCountU; 
pageNotifier: PeriodicNotify <- 

CreatePeriodicNotifty[window: window, results: ©results, milliseconds: 20000]; 

MyNotifyProc: NotifyProc = { 
input: Results; 

FOR input results, results. next do 
WITH z: input select from 
atom ss > 

IF z.a a updateCount THEN { 

— code to update page count on screen;} 

ELSE { 

— code to handle other atoms}-. 
endcase; 

ENDLOOP}; | 1 

46.3.2 Syntax of TIP tables 

Following is the BNF description for the syntax of tables. Non-terminals are boldface, 
terminals are non-bold Titan (e.g., Fas tMouse). The characters 

"=>", "{", and "}" in the BNF below are terminal symbols. The semantics are described 
in the next section. 

TIPTable :: = Options TriggerStmt . 

Note: tables terminate witJb a pericxi. 

Options :: = empty | OPTIONS OptionList ; 

OptionList :: = Option | Option , OptionList 

Option :: s SmallOrFast| FastOrSlowMouse 

SmallOrFast :: = Small | Fast 
FastOrSlowMouse :: = FastMouse | SlowMouse 

Expression :: = AND TriggerChoice | WHILE EnableChoice | => Statement 

Statement :: = TriggerStmt | EnableStmt | Results 

TriggerStmt :: = SELECT TRIGGER FROM TriggerChoiceSeries 

EnableStmt :: = SELECT ENABLE FROM EnableChoiceSeries 

TriggerChoiceSeries :: = TriggerChoice ; TriggerChoiceSeries 

I TriggerChoice ENDCASE FinalChoice 
I ENDCASE FinalChoice 
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EnabieChoiceSeries 



TriggerChoice 
EnableChoice 
FinalChoice 

TriggerTerm 
EnableTerm 

TimeOut 

KeyEnablelist 

Key 

Results 

Resultltemis 
ResuStitemi 



String 

Resultldent 

Keyldent 

Predicateldent 



: a EnableChoice ; EnabieChoiceSeries 
I EnableChoice ENDCASE FinalChoice 
I ENDCASE FinalChoice 

: = TriggerTerm Expression 
: s EnableTerm Expression 
: a empty | "> Statement 

:: = (Key I MOUSE I ENTER I EXIT) TimeOut 
:: = KeyEnablelist I Predicateldent 

:: = empty I BEFORE Number I AFTER Number 

= Key I Key | KeyEnablelist 
Note: the | between Key and KeyEnablelist is a 
terminal and must be entered. 
:: = Keyldent UP | Keyldent DOWN 

:: a Resultltem I Resultltem , Results | Resultltem Expression 

I { Resultltems } 
:: a Resultltem I Resultltem Resultltems 
:: a COORDS I BUFFEREDCHAR | CHAR | KEY | TIME 

I Number! String | Resultldent 

:: a "any sequence of characters not containing a "" 



a Ident 
a Ident 
a Ident 



46.3.3 Semantics of Tables 

The whole match process can be viewed as a select statement, that is continuously reading 
key transitions, mouse movements, or key states from the input queue. A trigger 
statement has the effect of looking at the next action recorded in the input queue and 
branching to the appropriate choice. An enable statement implies selection between the 
different choices according to the current state of the keyboard or the mouse keys. Trigger 
terms may appear in sequence, separated by and. They might be mixed with enable terms, 
which in turn are characterized by the keyword while. A timeout following a trigger 
indicates a timing condition that has to hold between this trigger and its predecessor. The 
number associated with the timeout expresses a time interval in milliseconds. Events 
starting with the same sequence of trigger and/or enable terms are expressed as nested 
statements. Result items may be identifiers, numbers, strings, or the keywords COORDS, 
BUFFEREDCHAR, CHAR, KEYS, or TIME. The results of a successfully parsed event are 
passed to the client. Numbers are passed as long integers, and strings as 
xstring.ReaderBodys. BUFFEREDCHAR and CHAR come as xsthng.ReaderBodys 
containing the character interpretation of the key involved with the event as defined by 
the CharTranslator. COORDS results in a window. Place containing the mouse coordinates 
of the event. 

Option :: a SmallOrFast | FastOrSlowMouse 
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SmallOrFast 



FastOrSlowMouse 

FastMouse 
SlowMouse 

Expression 



:: ■ Small | Fast 

TIP can produce its internal table in two formats: one designed 
for compactness (default) and one for speedy execution. This 
option indicates which format should be used. 

:: a FastMouse I SlowMouse 

The TriggerTerm MOUSE means all mouse movement. 

The TriggerTerm MOUSE means only the most recent mouse 

motion (default). 

:: = AND TriggerChoice | WHILE EnableChoice | => Statement 



AND TriggerChoice match if and only if TriggerChoice is the next input event after 

the preceding choice. For example, A Down AND B Down 
means A goes down and then B goes down (with no intervening 
actions like A Up or mouse motion). 

WHILE EnableChoice match if EnableChoice is also true at this point. For example, A 

Down WHILE B Down matches if A goes down while B is 
down. 



=> Statement 

Statement 

TriggerStmt 

EnableStmt 

EnableStmt 

TriggerStmt 

TriggerTerm 

Key 

MOUSE 

ENTER 
EXIT 

TimeOut 

BEFORE Number 



AFTER Number 



continue processing at Statement (it is used for results and 
common prefixes). 

:: s TriggerStmt I EnableStmt I Results 

:: = SELECT TRIGGER FROM TriggerChoiceSeries 

:: = SELECT ENABLE FROM EnableChoiceSeries 

matches if any of the EnableChoiceSeries have already 
happened. 

matches if any of the TriggerChoiceSeries have just happened. 

:: = (Key I MOUSE I ENTER I EXIT) TimeOut 

matches if the appropriate key transition occurs. 

matches if there is mouse motion (useful for tracking the 

mouse). 

matches if the mouse enters the window, 
matches if the mouse leaves the window. 

:: a empty I BEFORE Number I AFTER Number 

matches if the associated TriggerTerm happens within a number 
of milliseconds of the preceding (matched) user action. For 
example, A Down AND B Down BEFORE 200 would 
match if A went down and then B went down within 1/5 second 
(and there were no intervening actions). 

matches if the associated TriggerTerm happens a number of 
milliseconds or more after the preceding user action. For 
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EnableTerm 

KeyEnableList 

Key 

Key 

Keyldent 



Resultltem 

String 
Resultldent 

COORDS 

BUFFEREIDCHAR 



CHAR 
KEY 



TIME 

String 
Number 



example, A Down AND B Down AFTER 200 would 
match if A went down and then B went down more than 1/5 
second later (and there were no intervening actions). 

:: = KeyEnableList I Predicateldent 

is true if any of the Keys are true. 
:: = Keyldent UP | Keyldent DOWN 

is true if the appropriate transition has happened (if this is part 
of a trigger term, is the current user action; if this is an enable 
term, it has already happened). 

identifies the keyboard key. The identifiers should be one of: A 
... Z, One, Two, Three, ... Zero, Adjust, AGAIN, OpenQuote, 
DEFAULTS, BackSlash, BS, SUBSCRIPT, SMALLER, Comma, 
KEYBOARD, TAB, PROPS, COPY, Minus, DELETE, 
MARGINS, Equal, EXPAND, FIND, HELP, ITALICS, 
UNDERLINE, Keysetl, Keyset2, Keysets, Keyset4, Keysets, 
LeftBracket, LeftShift, LOCK, MouseMiddle, CENTER, MOVE, 
NEXT, SAME, Period, Point, CloseQuote, SUPERSCRIPT, 
RETURN, RightBracket, RightShift, BOLD, SemiColon, Slash, 
Space, OPEN, PARATAB, UNDO, STOP, A8, A9, AID, All, 
A12, LI, L4, L7, LIO, Key47, R3, R4, R9, RIO 

Note: There are no names for shifted characters like left or right 
paren. Instead, specify one or both shift keys plus the unshifted 
key name. For example, Nine Down WHILE LeftShift Down 
instead of LeftParen Down. 

See LevellVKeys and the Pilot Programmer s Manual for 
(610E00160) more information on the keyboard. 

= COORDS|BUFFEREDCHAR|CHAR|KEY|TIME 
I String | Number | Resultldent 
:: = "any sequence of characters not containing a "" 
:: a Ident 

return a coord ResultElement with the coords of the last user 
action. 

return a string ResultElement containing the character 
representations of the last user actions that were also buffered 
characters. 

same as BUFFEREDCHAR 

return a key ResultElement with the current state of the key 
(not recommended in normal usage. Usually a more complex 
TIP table is indicated if you are using this result), 
return a time ResultElement with the time of the last (matched) 
user action. 

return a string ResultElement. 
return an integer ResultElement. 
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Resultldent return an atom ResultElement. 




Predicateldent -aldent 

Predicateldent is not currently implemented. 

46.3.4 Example Table 

SELECT TRIGGER FROM 
Point Down => 

SELECT TRIGGER FROM 

Point Up BEFORE 200 AND Point Down BEFORE 200 => 
SELECT ENABLE FROM 

LeftShift Down = > COORDS, Shi f tedDoubleCl ick 
ENDCASE => COORDS, NormalDoubleCl ick ; 

Adjust Down BEFORE 300 => Po intAndAd j us t ; 
ENDCASE => COORDS, SimpleClick; 



This table produces the result element (atom) NormalDoubleCl ick along with the 
mouse coordinates if the left mouse button goes down, remains there not longer than 
200 ms, and goes down again before another 200-ms elapse. The result is 
ShiftedDoubleClick if the same actions occur but also the left shift key is down. If 
the right mouse button also goes down less than 300 ms after the initial Point Down 
and the left mouse button also goes down, Po intAndAd just results.. Finally, the 
table specifies the result SimpleClick (with coordinates) if Point goes down but none 
of the above-described succeeding actions occurs. 

46.3.5 Simple TIP Client Example 

This example shows a simple TIP client. The window acts in the following manner. If the 
left (Point) mouse button is depressed the window becomes the input focus and the 
cursor changes to its special shape. As long as the window is the input focus and the 
cursor is in the window, it remains the special shape but returns to the original shape 
when the mouse leaves the window. The place in the window where the depressed left ( 
Point) mouse button is released is the place where text is displayed. 

The procedure InitAtoms is part of the initialization code and creates the four atoms 
that the notify procedure understands. It is put in a separate procedure so the string 
literals will not be allocated in the global frame. The procedure InitWindow initializes 
the window by attaching the context data and setting the table and notify procedure. 

This example uses the system's table from TIPStar. The fragments of the 
NormalMouse.tip portion of TIPStar's normal table that are used to generate the atom 
results in this example are 

Point Down => SELECT ENABLE FROM 

ISHIFT1=> TIME, COORDS, Shift, PointDown; 
ENDCASE => TIME, COORDS, PointDown; 

Point Up => SELECT ENABLE FROM 

ISHIFT1=> TIME, COORDS, Shift, PointUp; 
ENDCASE => TIME, COORDS, PointUp; 
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ENTER = > Enter; 
EXIT = > Exit; 

The notify procedure TIPMe looks at the results and understands four atoms and string 
input. For the atom pointDown, if the window is not already the input focus, it sets the 
window as the input focus and sets the cursor to its special shape. For the atom pointUp, 
it saves the place the event occurred as the location to display text. The enter atom just 
fiddles with the cursor if the window is the input focus. The exit atom restores the 
cursor. If the window is the input focus and the user types int6 the window, a string 
result is sent to the notify procedure containing the characters typed. The 
NormalKeyboard.tip portion of TIPStar's normal table contains the bufferedchar results 
for the keyboard-keys-going down events. 

Handle: TYPE = long pointer to Object; 
Object: type » . . .; 

contextlyipe: Context.Type = context.UniqueType[]; 
pointDown, pointUp, enter, exit: Atom.ATOM; 

InitAtoms:: procedure s { 

pointDown <— Atom,MakeAtom("PointDown"L]; 
pointUp Atom.MakeAtom["PointUp"L]; 
enter <<- Atom.MakeAtom("Enter"L]; 
exit <r- Atom.Mal<eAtom["Exit"Ll}; 

InitWindow: procedure [window: window. Handle] = { 
h: Handle a zone. NEw[Object <-[]]; 

Context.Create[type: contextType, data: h, proc: DestroyContext, window: window]; 
TiP.SetTableAndNotifyProct 

window: window, table: TiPStar-NormalTableHf notify: TIPMe]}; 

TIPMe: TiP.NotifyProc a { 

h: Handle » Context.Findftype: contextType, window: window]; 
place: window. Place; 

FOR input: TiP.Results <r- results, input.next until input = nil do 
WITH it: input select from 
coords = > place <~ z. place; 
atom = > SELECT z.a from 
pointDown a > 

IF -h.haslnputFocus then { 
TiP.SetlnputFocus[ 

window: window, takeslnput: true, 
newlnputFocus: MyLosingFocusProc, clientData: h]; 
SaveCursorAndSetMine[h]} 
pointUp a > h.textPlace <~ place; 

enter a > if h.haslnputFocus then SaveCursorAndSetMine[h]; 
exit a > RestoreCursor[h]; 
enocase; 
string a > 

h.textPlace <- DisplayTextAtPlace[h: h, reader: @z.rb, place: h.textPlace]; 
endcase; 

ENDLOOP}; 
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MyLosingFocusProc: TiP.LosingFocusProc = { 
OPEN h: NARROw[clientData, Handle]; 
h.haslnputFocus «- false}; 

46.3.6 Modifying an Existing TIP Client 

This example shows how an existing TIP client may be modified. Assuming the 
existence of a TextWindow package similiar to that in Tajo, this example builds a TTY- 
like window on top of it. It modifies the text window's behavior in two ways. First, it 
changes the table that the text window uses by linking its own table on the front of the 
normal table that the text window package uses. It also has its own notify procedure 
that just looks for the STOP key going down but passes all other notifications to the text 
window's notify procedure that it saves. 

This example writes its own table. The table maps shift backspace to the character 
Control- W, backspace to the character Control- H, the DELETE key to the DEL character 
and the TAB key to the ESCAPE character. This table handles only a few of the 
functions and is linked onto TIPStar's normal table to provide the bulk of the funtion. 

-- File: TTY.tip 

[DEF SHIFT, (LeftShift Down | RightShift Down | Key47 Down | A12 Down)] 

SELECT TRIGGER FROM 

BS Down => SELECT ENABLE FROM 
[SHIFT] => "\027"; 
ENDCASE => "\010•^• 
DELETE Down => "\177"; 
TAB Down => "\033"; 
ENDCASE. 

Handle: TYPE = long pointer to Object; 
Object: type s . . .; 

contextType: Context.Type a context.UniqueType[]; 
stop: Atom.ATOM; 

Init: PROCEDURE a { 

rb: XString.ReaderBody <- XString.FromSTRING["TTY.tip"L]; 
stop^ Atom.MakeAtom["Stop"L]; 
myTable <-TIP.CreateTable[file: @rb]; 

[] <-TIP.SetTableLink[from: myTable,to: TIPStar.NormalTable[]}; 

Create: procedure [window: window. Handle, ...]»{ 
h: Handle a zone.NEw[Object <- []]; 
TextWindow.Create[window, . . .]; 

h.oldNotify <-Tip.SetNotifyProc[window: window, notify: TIPMe]}; 

TIPMe: TiP.NotifyProc = { 

h: Handle = Context.Find[type: contextType, window: window]; 
WITH z: results select from 
atom s > select z.a from 
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stop = > { 

TiP.FlushUserlnput[]; 

SendHaltNotification[h]; 

return}; 
enocase; 

h.oldNotify[window, results]}; — normally pass results to text window's notify 

46.3.7 Macro Package 

The macro package used in TIP is based on the general-purpose macrogenerator 
described by Strachey in Computer Journal (October 1965). The following summary is 
based on that article; see the article itself for more details. 

A macro call consists of a macro name and a list of actual parameters, each separated by 
a comma. The name is preceded by a left square bracket ([), and the last parameter is 
followed by a right square bracket. A macro is defined by the special macro DEF, which 
takes two arguments: the name of the macro to be defined and the defining string. The 
defining string may contain the special symbols ~l, ~2, etc., which stand for the first, 
second, etc., formal parameters. Enclosing any string in parentheses prevents 
evaluation of any macro calls inside; in place of evaluation, one layer of string quotes is 
removed. It is usual to enclose the defining string of a macro definition in string quotes 
to prevent any macro calls or uses of formal parameters from being effective during the 
process of definition. 

Here are some sample macros and an example: 

— macro definitions 
[DEF,LSHIFT, (LeftShif t Down)] 
[DEF,RSHIFT, (RightShift Down)] 
[DEF,EitherShif t, ( 

[LSHIFT] => -1; 
[RSHIFT] => ~1)] 

— trigger cases 
SELECT TRIGGER FROM 

BS Down => SELECT ENABLE FROM 
[EitherShif t,{BackWord}l ; 
ENDCASE => {Backspace}; 

— more cases . . . 
ENDCASE . . . 

The above example expands to: 

BS Down => SELECT ENABLE FROM 
LeftShift Down => BackWord; 
RightShift Down = > BackWord; 
ENDCASE => {Backspace}; 
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46.4 Index of Interface Items 



Item 


Page 


Item 


Page 


actionToWindow: array of boolean 


11 


KeyToCharProc: type 


7 


ATOM: TYPE 


4 


LoslngFocusProc: type 


7 


AttentionProc: type 


10 


Manager: type 


9 


backStoplnputFocus: window.Handle 


7 


NotifyProc: type 


4 


CailBack: procedure 


8 


nullManager: Manager 


9 


CallBackNotifyProc: type 


9 


nullPeriodlcNotify: PeriodicNotify 


8 


CanceiPeriodicNotify: procedure 


8 


PeriodicNotify: type 


8 


caretRate: Process.Ticks 


11 


ResetUserAbort: procedure 


9 


CharTranslator: type 


7 


ResultObject: type 


4 


ClearlnputFocusOnMatch: procedure 


7 


Results: type 


4 


ClearManager: procedure 


9 


ReturnToNotlfier: error 


111 


clickTimeout: System. Pulses 


11 


SetAttention : procedure 


10 


CreateCharTable: procedure 


6 


SetBackStoplnputFocus: procedure 


7 


CreatePeriodicNotify: procedure 


8 


SetCharTranslator: procedure 


8 


CreatePlaceHolderTable: procedure 


6 


SetlnputFocus: procedure 


7 


CreateTable: procedure 


6 


SetManager: procedure 


9 


Destroy Table: procedure 


6 


SetNotlfyProc: procedure 




OownUp: TYPE 


4 


SetNotifyProcForTable: procedure 


() 


Error: error 


11 


SetTable: procedure 


;> 


ErrorCode: type 


11 


SetTableAndNotifyProc: procedure 


;> 


FlushUserlnput: procedure 


11 


SetTableLink: procedure 


;> 


FocusTakeslnput: procedure 


7 


SetTableOpacity: procedure 


;> 


GetCharTranslator: procedure 


8 


SetUserAbort; procedure 


9 


GetlnputFocus: procedure 


7 


StuffCharacter: procedure 


10 


GetManager: procedure 


9 


Stuff CurrentSelection: procedure 


10 


GetNotifyProc: procedure 


5 


StuffResults: procedure 


10 


GetNotifyProcFromTable: procedure 


6 


StuffSTRING: procedure 


10 


GetPlace: procedure 


11 


StuffString: procedure 


10 


GetTable: procedure 


5 


StuffTrashBin: procedure 


10 


GetTableLink: procedure 


5 


Table: type 


;> 


GetTableOpacity: procedure 


5 


TableError: type 


ri 


InvalidTable: signal 


11 


TableObject: type 


!> 


KeyBits:TYPE 


8 


UserAbort: procedure 


9 


KeyName: type 


4 


WaitSeconds: procedure 


11 
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47.1 Overview 

The TIP facility provides a mechanism that links a list of TIP. Tables. These tip. Tables 
contain productions that translate user actions into terms a client is prepared to deal with. 
TIPStar creates a structure for the list of ViewPoint TIP tables to be built on. This structure 
divides all possible input actions into logical groups (mouse actions, special keys like 
UNDO and STOP, utility keys like MOVE and COPY, etc.) and provides a means for accessing 
these groups of tables. 

47.2 Interface Items 



47.2. 1 The TIPStar Structure 

The basis for the TIPStar structure is the placeholder. 

Placeholder: type a {mouseActions, keyOverrides, softKeys, keyboardSpecific, 
blackKeys, sideKeys, backstopSpecialFocus}; 

A placeholder table is created for each of the enumerateds in Placeholder. Placeholder 
tables are empty TIP tables linked to form a list. This list divides all possible input actions 
into logicsd groupings as discussed in the Overview above. This defines a series of 
segments for the list of TIP. Tables to be built upon. Segments (mini-stacks) are delineated 
by the placeholder tables. This initial list of TiP.Tables then, contains only empty tables. 
Note: Placeholder tables will always be empty. They are as their name implies, 
placeholders—each providing a position in the list of tables for adding or removing real 
tables of a particular kind (those relating to mouse actions, those mentioning the soft 
keys, etc.). See Examples in the next section. 

Fine Point: A set of normal tables that contain all the basic key productions is installed at boot time. See the 
System TIP Tables Appendix for listings of those tables and a view of the TIP Table list at the completion of 
booting. These normal tables are referred to as generic in the description of TiPStar.GetTable to prevent confusion 
with the procedure TiPStar.NormalTable. 
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The list of ViewPoint placeholder tables is initialized as in Figure 47.1 (the arrows 
represent the links of the list). 



Placeholders 


input & Uses 




mouseActions 






r 






keyOverrides 


To or PROPQ AAzVion TiT'A'ncM^'fv Gnoof ic iit^I 




f 






softKeys 






r 






keyboardSpecific 


Kpv<? on nhv^ipiillv Hiffprpnt Icpvhn^irfl^ 




r 






blackKeys 


Thp nhvsipfil WpvhofirH iinH it.c* morlifirjitiorm 

I. L/ilV iJ±\^<Xl IVv^ V f-JKfCkl. V4 diXvft. LKlkJ ill l_/vt XA A^Cl WAV./ I AO . 




r 






backstopSpecial Focus 


All those not directed to the input focus. 










NIL 


Handles STOP, KEYBOARD, UNDO, and friends. 









Figure 47. 1 ViewPoint Placeholder Tables 

47.2.2 Installing and Removing Tables 

A client may alter the table arrangement by pushing or storing a TIP table into any point 
on the tree, or by popping back to a previous table. 

PushTable: procedure [Placeholder, TiP.Table] ; 

PushTable leaves old tables in the watershed, but places the new table (or chain of tables) 
directly after the specified placeholder. This places the new table in front of any others 
within that segment. Thus if the new table mentions the same key actions as the old table, 
the old one is effectively ignored until the new one is popped. If the new table only 
mentions a few key actions, however, previously pushed tables will be used for the others. 

For an example of PushTable and the resulting TiP.Table list, see §47.3.1. 

PopTabie: procedure [Placeholder, TiP.Table] ; 

PopTable takes the single TIP table to be popped. It is not required that the table to be 
popped be at the top of the placeholder's list. A strict stack discipline is relaxed. 



47-2 



Viewpoint Programmer's Manual 



47 



StoreTable: procedure [Placeholder, Tip.Table] returns [Tip.Table] ; 

StoreTable replaces the table (or chain of tables) with the client's table (or chain of tables) 
and returns the previous table. The client can restore the old value later, if it wishes. (In 
using StoreTable, and especially remembering/restoring the old value, the client probably 
needs to be cognizant of the other clients that may manipulate the same placeholder.) See 
examples in §47.3.3. 

47.2.3 Retrieving Pointers to Installed Tables 

NormalTable: procedure [Tip.Table]; 

NormalTable returns the table at the head of the list (mouseActions placeholder). This is 
the appropriate table to use for a normal TiP.SetTableAndNotifyProc. 

GetTable: PROCEDURE [Placeholder] returns [Tip.Table]; 

GetTable returns the generic table at the specified placeholder, if one exists. (See the Fine 
Point in §47.2.1.) 

47.2.4 Mouse Modes 

Mode: TYPE a {normal, copy, move, sameAs}; 

The TiPStar.Modes refer to the various modes attributable to mouse actions. These modes 
can be programmatically checked and changed using the GetMode and SetMode 
procedures outlined below. 

GetMode:pROCEDURE returns [mode: Mode]; 

GetMode returns the current mode. 

SetMode: procedure [mode: Mode] returns [old: Mode]; 

Calling SetMode causes the appropriate Tip.Table to be stored in the TiPStar chain. 

For example, when the COPY key goes down, the call to TiPStar.SetMode[copy] causes 
NormalMouso.TIP to be relaced by CopyModeMouse.TIP. Clients receiving mouse notifications 
receive CopyModeDown instead of PointDown. If the world was in move mode (causing 
MoveModeMouse.TIP to be stored) the client would receive the MoveModeDown when 
mouse point was pressed. See the TIP Table Appendix for information on the other 
productions in the four mouse tables (NormalMouse.TIP, CopyModeMouse.TIP, 
MoveModeMouse.TIP and SameAsModeMouse.TIP). 
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47.3 Usage/Examples 



47.3.1 When PushTable Is Called 



InitializeMyTIPTables. procedure = 

BEGIN 

rbClientAMouse: xstring.ReaderBody <- xstring.FromSTRINGt"ClientAMouse.TiP"L]; 
tipClientAMouse: Tip.Table «-TiP.CreateTable[file: @rbCiientAMousel; 

— install my tip table (tie it to my notify proc) 

l]<-TiP.SetNotifyProcForTable( tipClientAMouse. ClientAMouseNotifyProc]; 
PushTableCmouseActions. tipClientAMouse],- 

rbClientAKeys: xstring.ReaderBody <-xstring.FromSTRINGl"ClientAKeys.TiP"L]; 
tipClientAKeys: Tip.Table <-Tip.CreateTable(file: ©rbClientAKeysl; 

— install my tip table (tie it to my notify proc) 

[l<-TiP.SetNotifyProcForTable( tipClientAKeys, ClientAKeysNotifyProc]; 
PushTabletsideKeys, tipClientAKeys); 
END; -- InitializeMyTIPTables 

Assume initially the list appears as in Figure 47.1. If Client A then pushes two tables onto 
that list, as in the code above, the new links result in the list shown in Figure 47.2.. 



mouseActions 


► 


ClientAMouse.TIP 










keyOverrides 


4 1 



softKeys 



keyboardSpecific 



blackKeys 



sideKeys 



ClientAKeys.TIP 



backstopSpecial Focus ^ 



NIL 



Figure 47.2 When PushTable Is Called 
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If client B then pushes another table to the mouseActions placeholder 
PushTablelmouseActlons, tipClientBMouse); 

the resulting list appears as in Figure 47.3. 



mouseActions 



keyOverrides 



1 



soft Keys 



i 



keyboardSpecific 



1 



blackKeys 



i 



side Keys 



backstopSpecial Focus 



1 



NIL 



ClientBMouse.TIP 



ClientAMouse.TIP 



> ClientAKeys.TIP 



Figure 47.3 Pushing Another Table 



47.3.2 When StoreTable Is Called 

rbClientCMouse: xstiing.ReaderBody «- xstring.FromSTRINGC'CIientCMouse.TiP "l]; 
tipClientCMouse: Tip.Table <-Tip.CreateTable[file: ©rbClientCMouse]; 
-- install my tip table (tie it to my notify proc) 

n<-TiP.SetNotifyProcForTablet tipClientCMouse, ClientCMouseNotifyProc]; 
savedTable <- StoreTabie[mouseActions, tipClientCMouse]; 

Assume initially the list appears as in Figure 47.3. If client C then calls StoreTable with 
another table directed at the mouseActions placeholder, the resulting list appears as in 
Figure 47.4. 
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mouseActions 



keyOverrides 



softKeys 



1 



keyboardSpecific 



i 



blackKeys 



sideKeys 



backstopSpecial Focus 



ClientCMouse.TIP 



ClientAKeys.TIP 



NIL 



Figure 47.4 Pushing Another Table 



Client C will now have the handle to the segment removed from mouseActions when the 
StoreTable was done (savedTable, see Figure 47.5). This table (or in this case, chain of 
tables) should be replaced when the client is through with its own mouse tip 
(tipCllentCMouse) by a call to: 



StoreTable[mouseActions, savedTable]; or 
PopTabie[mouseActions, ti pCI ientCMouse] ; 
PushTable[nnouseActions, savedTable] ; 







ClientBMouse.TIP 






r 




ClientAMouse.TIP 







Figure 47.5 Saved Table 
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47.3.3 When PopTable Is Called 



Assume initially the list appears as in Figure 47.3. If client A then pops its table at the 
mouseActions placeholder, the resulting list appears as in Figure 47.6. Note: It is not 
necessary for the table being popped to be at the top of the stack (where the top of a stack is 
here defined to be the position immediately following any placeholder table-thus there 
are several stacks within the watershed list of tables). 



mouseActions 



ClientBMouse.TIP 



keyOverrides 



softKeys 



keyboardSpecific 



i 



blackKeys 



sideKeys 



ClientAKeys.TIP 



backstopSpecial Focus 



i 



NIL 



Figure 47.6 Pop Table 
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47.4 Index of Interface Items 



Item 


Page 


GetMode: procedure 


3 


GetTable: procedure 


3 


NormalTable: procedure 


3 


Mode: type 


3 


Placeholder: type 


1 


PopTable: procedure 


2 


PushTable: procedure 


2 


SetMode: procedure 


3 


StoreTable: procedure 


2 
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48.1 Overview 



The Undo interface provides a set of procedures that allow applications to add Undo 
opportunities to the current Undo stack. An implementation of Undo can then call 
applications when the UNDO key is depressed. 



48.2 Interface Items 

48.2.1 Application's Procedures 
Opportunity; undo.Proc; 



PrOC: TYPE s PROCEDURE [ 

undoProc: procedure [long pointer], 
destroyProc: procedure [long pointer], 
data: long pointer, 
size: cardinal <-0 ]; 

The Opportunity procedure is called by an application when it does something that can be 
undone. The client's undoProc is called to perform an undo. The destroyProc is called 
when the undo opportunity no longer exists. The client can destroy any data at that time. 
The undoProc or the destroyProc will always be called. The client's context for the 
undoing is passed in via the data item: a non-zero size indicates that the Undo 
implementation should copy the words from data \ through (data + size-1) f into its zone. 
If size = 0, the caller's long pointer is simply remembered. 

Roadblock: procedure [xstring. Reader]; 

The Roadblock procedure is called by an application when it does something that cannot 
be undone. The immutable string passed in is a message that the Undo implementation 
can issue if the user attempts to undo past this point. The string is copied. 

DoAnUndo: procedure; 
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The DoAnUndo procedure is called when an undo action should be forced. Typically this 
will be when the keyboard modules notice that UNDO has been pressed. 

DoAnUnundo: procedure; 

The DoAnUnundo procedure is called when an un-undo action should be forced. Typically 
this will be when the keyboard modules notice that shift-UNDO has been pressed. 

DeieteAli: procedure; 

The DeleteAil procedure is called to tell the Undo implementation to empty its stack of 
opportunities. Typically this procedure will be called upon logoff. 

48.2.2 Implementation's Procedures 

Setlmplementation: procedure [ 

undo.lmplementation] returns [Implementation]; 

Getlmplementation: procedure returns [Implementation]; 

Implementation: type « record [ 
opportunity: undo.Proc, 
roadblock: procedure [xstring.Reader], 
doAnUndo: procedure, 
doAnUnundo: procedure, 
deleteAII: procedure ]; 

These procedures allow an implementation to plug itself in to the Undo mechanism. An 
implementation can supply its set of procedures, and can ascertain the current procedures. 
Setlmplementation returns the procedures of the previous implementation. 

An initial set of dummy procedures are provided. They are basically no-ops; the dummy 
Opportunity procedure immediately calls the application's opportunity. destroyProc. 

Zone: procedure returns [uncounted zone] 

Returns the implementation's zone. 

48,3 Usage/Examples 

The application calls Opportunity with some context. The Undo implementation will 
eventually call the application either at its undoProc or its destroyProc. The former is 
called upon a real undo request. The latter is called when the opportunity is about to be 
forgotten: it allows the application to garbage-collect context. The destroyProc is typically 
called to prune the undo stack of very old elements or to prune opportunities that are 
trapped behind a roadblock. 

At the application's undoProc or destroyProc, the argument is either (1) the original 
pointer passed in to Opportunity, if size was zero or (2) a pointer into the Undo 
implementation's zone that points to a copy of the application's data. In the latter case, the 
data will be freed by the Undo implementation right after the call. Exception: if the help 
implementation is a no-op implementation, it can call the application's destroyProc from 
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inside the Opportunity call. In this case, the help implementation can present the original 
pointer to the destroyProc even if size is non-zero. 

48.3.1 Example 

MyUndoDataObject: type = record [...]; 

MyllndoData: type = long pointer TO MyUndoDataObject; 

complaint: xstring.ReaderBody <~xstring.FromSTRING ["Can't do thaf'Ll; 

UndoProc: PROCEDURE [myUndoData: MyUndoData] = { 

— does something appropriate, like a partial cleanup of data structures.message 
-- might post a about current state for the user. 
undo.Zone [].FREE [@myUndoData]; 

}; 

DestroyProc: procedure [myUndoData: MyUndoData] = { 
Undo.Zone [].FREE [@myUndoData]; 
}: 

— Mainline code 

Code that cannot be undone 

undo.Roadblock [©complaint]; 

— Code that can be undone 

Undo.Zone[].NEw[MyUndoDataObject [...] ]; 

undo.Opportunity [undoProc: UndoProc, destroyProc: DestroyProc, data; myData]; 
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48.4 Index of Interface Items 



Item Page 

DeleteAII: procedure 2 

DoAnUndo: procedure 1 

DoAnUnundo: PROCEDURE 2 

Getlmplementation: procedure 2 

Implementation: type 2 

Opportunity: procedure 1 

Proc: TYPE 1 

Roadblock: procedure 1 

Setlmplementation:PROCEDURE 2 

Zone: procedure 2 
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49.1 Overview 

UnitConversion provides for converting numbers between various units of measure. 

49.2 Interface Items 

Units: type = {inch, mm, cm, mica, point, pixel, pica, didotPoint, cicero}; 

Units defines all the units that may be converted, point is printer point, pixel is screen dot. 
pica = 12 points. 

ConvertReal: procedure [n: XLReai.Number, inputUnits, outputUnits: Units] 
RETURNS [xLReai.NumberJ; 

ConvertReal converts n from inputUnits to outputUnits, using XLReal. May raise 
XLReal. Error. 

Convertlnteger: procedure fn: long integer, inputUnits, outputUnits: Units] 

RETURNS [long INTEGER]; 

Convertlnteger converts n from inputUnits to outputUnits. May raise XLReal. Error 

49.3 Usage/Examples 

49.3.1 Converting Font Values 

The following example implements a real number conversion utility: 

Unit: type ■ machine dependent {inch(O), mm(1), mica(2), point(3), space(4), cm(5), (15)}; 

Convert: public PR0C[n: XLReai.Number, inputUnits, outputUnits: Unit.Units] 
RETURNS [XLReai.Number] » { 
IF inputUnits a outputUnits then return [n]; 
if inputUnits s space then 
return 

UnitConversion.ConvertReal[ 
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XLReai.Muitipiy[n, pointPerSpace],seventySecondOfAninch, 
Con vertU n its(outputU n its]] ; 
iFoutputUnits ■ space THEN 

RETURN 

XLReai.Divide[unitConversion.ConvertReal[n, ConvertUnits[inputUnits], 
seventySecondOfAnlnch], pointPerSpace]; 

RETURN 

UnitConversion.ConvertReai[ 

n, ConvertUnits[inputUnits], ConvertUnits[outputUnits]]}; 

ConvertUnits: PROc[u: Units] RETURNS [UnitConversion. Units] » { 
iFu < mica THEN RETURN [val[u.0RD1]; 
iFu 3 mica THEN RETURN [val[u.ORD + 1]]; 

IFU a point THEN RETURN [vAL[u.ORD + 6]]; 
RETURN [cm] 

}; 
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49.4 Index of Interface Items 

Item Page 

Convertlnteger: procedure 1 
ConvertReal: procedure 1 
Units: type 1 
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50.1 Overview 

The Window interface supplies facilities for managing windows on the display screen. A 
window is a rectangular region of the display screen in which a client can display 
information to the user. A window may overlap another window or even completely cover 
it. A window may extend past the edges of the physical display screen or even be 
completely outside it, and thus not visible. Windows may be moved around horizontally 
and vertically, have their size changed, and have their depth changed in the stack of 
windows visible on the screen. Window shields the client from these considerations-from 
^"•"•"'^ the client's point of view, each window is unaffected by other windows x>v by the edges of 

the display screen. Window automatically handles client requests to paint into window 
regions that are not currently visible on the screen. 

The Display interface supplies routines for painting into windows. 

50.1.1 Window Creation 

Window supplies operations to allocate and free a window (a window. Object). However, 
windows are usually not allocated directly by clients, but rather are obtained from various 
other facilities, such as StarWindowSheil or FormWindow. Once allocated, a window is 
referred to and manipulated by reference, using a window.Handle. 

50.1.2 Child Windows and the Window Tree 

Window manipulates a tree of windows. A window may have child windows. Child 
windows obscure their parent; that is, they are above their parent in the apparent stack of 
windows visible on the screen. A child window may be entirely contained within its 
parent's screen area, may project beyond its parent's edges, or even be completely outside 
its parent. Window automatically clips the display of a child window at its parent's edges. 
Thus a child window that is completely outside of its parent will not be visible on the 
screen at all. 

Each window has an ordered list or stack of its child windows. Sibling windows may 
overlap: if they do, one that appears earlier in the stack is on top of or obscures one that 
appears later. The first window in the stack is the top sibling, and the last is the bottom 
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sibling. Each window has a pointer to its parent, a pointer to the next sibling of its parent, 
and a pointer to the window's topmost child. 

When a window is created, it is not in the window tree, and is called a private window. A 
private window is unknown to Window and is not displayed on the screen. Window 
provides facilities for inserting private windows into the tree, moving them within the 
tree, and removing them from it. A window that is in the tree will be wholly or partially 
visible on the screen unless it is entirely outside its parent's area or its children 
completely cover the portion that is within its parent. Private windows may also be built 
into private trees, which can be inserted into and removed from the window tree as a unit. 

Display supplies the root window, which is the root of the window tree and corresponds to 
the entire display screen. The root window typically supplies the background pattern. 

Each window has its own coordinate system: the upper-left corner is the origin [x: 0, y: 0], 
with X increasing to the right and y increasing downward. A window's location is defined 
in terms of its parent's window's coordinate system. Coordinates may be positive or 
negative, and thus a window can have any location relative to its parent. 

50.1.3 Painting into a Window 

Every window contains a client-supplied display procedure that will, on demand, paint all 
or part of the window. Note that windows can be much larger than the display screen; any 
paint directed to non-visible portions of a window-or outside the window entirely-is 
discarded. Thus a client never needs to be concerned about what parts of its window are 
covered by other windows or what parts are off the screen. As a convenience to clients, 
requests to paint into a window that is not currently in the window tree are also ignored. 

The Display and SimpleTextDisplay interfaces provide a variety of procedures for painting 
various things into a window, including character strings, black, white, or gray boxes, and 
various graphics, such as curves and lines. 



The display background color, which is represented by a pixel value of zero, is commonly 
called white and a value of one is called black. Note: The display hardware also can render 
the picture using zero for black and one for white. Clearing or erasing an area of the screen 
means setting all of its pixels to zero, or white. 

It is common that a display procedure wants to start with an erased (zero) area and 
logically OR the black pixels into the area. Window supplies an accelerator 
clearingRequired to minimize unnecessary erasures. If clearingRequired = true. Window 
guarantees that when the display procedure is called to paint the window, all of the 
window's pixels that should be white indeed are white. In that situation, the window 
might contain any combination of its previous contents and erased areas. On the other 
hand, some display procedures will want to set all pixel values, completely overwriting the 
previous contents. These windows should specify clearingRequired s false. 

Areas displayed on the screen may become incorrect or invalid for many reasons, such as 
when a window that was visible is deleted. A client can also mark an area invalid. 
Window accumulates these invalid areas and then, in response to a client call to Validate 
or ValidateTree, calls the various windows' display procedures to paint the necessary 
areas. Validate and ValidateTree are the only Window operations that cause immediate 
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screen painting. All other operations merely enqueue work to be performed by a later 
^Ifgl/ Validate operation. Fine Point: The few special cases that do not follow this rule are noted in the text. 

The standard way for a client to paint into its window is to update its data structures, 
invalidate the portion of its window that needs to be painted, and then call a Validate 
routine. Window responds by calling back into the client's display procedure to do the 
painting. 

When a window's display procedure is called, it has access to a list of the invalid areas of 
the window. It may choose to paint the entire window or, alternatively, to enumerate the 
invalid areas and just paint those areas. In any case. Window clips all of the display 
routine's paint requests to the boundaries of the invalid areas-paint directed to other 
areas is discarded. In special circumstances, the client may wish to paint into valid visible 
areas. The operation FreeBadPhosphorList deletes the display routine's invalid area list; 
for the lifetime of that invocation of that display procedure, paint requests will be clipped 
only to the boundaries of the visible parts of the window. 

If display routines are called from outside the invocation of a window's display procedure, 
the paint requests will be clipped to the boundaries of the visible parts of the window. 



50.1.4 Bitmap-under 

The window package allows clients to associate a window with a bitmap-under. This is a 
block of memory that is used to hold the pixels that are covered up by the window. This 
facility allows Window to move or delete such a window quickly, since it can repaint the 
display directly using the contents of the bitmap-under instead of calling client display 
procedures. A bitmap-under is commonly used for menu windows. 



50.1.5 Window Panes 

The window package normally maintains a detailed list of invalid regions and allows 
arbitrary overlapping of windows without requiring the client to worry about other 
windows. Some clients would prefer to have greater control over their windows at the 
expense of more restrictions over their use. Window panes are such a mechanism. If a 
window is a window pane, the client must assure that it doesn't overlap any of its siblings 
and that the parent doesn't paint underneath the pane. A further restriction is that only 
window panes may be children of panes. In return, the window package can do much less 
calculation to determine invalid regions. The window package does not enforce these 
restrictions. It is up to the client to follow them, or inconsistent screen appearance may 
result. The client must specify whether a window is a window pane when it is initialized. 

50.2 Interface Items 

50.2.1 Basic Data Types and Utility Operations 

This section describes basic Window data types and utility procedures. 
Handle: type = long pointer to Object; 
Object: type [19]; 
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Object is the storage that represents a window. A Handle is used to refer to the window. 
Clients should not allocate objects directly but must use operations described in §50.2.2. 

rootWindow: readonly Handle; 

Root: PROCEDURE RETURNS [Handle] = INLINE {RETURNfrootWindow]}; 

rootWindow is the window that is the root of the window tree. The procedure Root is 
provided for compatibility with previous versions; new applications should use 
rootWindow instead. 

MinusLandBitmapUnder: type [6]; 

MinusLandBitmapUnder is additional storage for windows that may have bitmap-unders. 
MinusLandColor: type [1]; 

MinusLandCoior is not used in the current release. 
MinusLandCookieCutter: type [2]; 

MinusLandCookieCutter is not used in the current release. 
Place: TYPE a userTerminai.Coordinate; - [x, y: integer]; 

Place is a position in a window. It is measured relative to the window's upper-left corner, 
which is defined to be at [x: 0, y: 0]. x increases to the right, y increases downward. Note 
that the coordinates may be negative. 

Dims: type = record [w, h: integer]; 

Dims is the size of a rectangular box. The rectangle is w pixels wide and h pixels high. 
Box: TYPE = RECORD [place: Place, dims: Dims]; 
BoxHandle: type = long pointer to Box; 
nullBox: Box » [place: [0,0], dims: [0,0]]; 

Box describes completely a rectangular box. place describes the upper-leftmost pixel of the 
box, and dims describes the size of the box. The box extends to the right and downward 
from place. As always, place is expressed in its containing window's coordinate system. 

BoxesAreDisjoint: procedure [a, b: Box] returns [boolean]; 

BoxesAreDisjoint returns true if a and b do not intersect. 

intersectBoxes: procedure [b1, b2: Box] returns [box: Box]; 

IntersectBoxes returns a Box that is the intersection of b1 and b2. If their intersection is 
empty, this operation returns box. dims = [0,0]. 
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IsPlacelnBox: procedure [place: Place, box: Box] returns [boolean]; 
IsPlacelnBox returns true if place is a pixel of box. 

BitmapPlace: procedure [window: Handle, place: Place <- [0,0]] returns [Place]; 

BitmapPlace returns the coordinates in the root window that correspond to place in 
window. 

BitmapPlaceToWindowAndPlace: procedure [bitmapPlace: Place] 
returns [window: Handle, place: Place]; 

BitmapPlaceToWindowAndPlace returns the topmost visible window and the coordinates 
within it that correspond to bitmapPlace in the root window. 

50.2.2 Window Creation and Initialization 

A window is created by the client allocating and initializing a window. Object. Many times 
windows are not created directly by clients, but rather are obtained from various other 
facilities, such as StarWindowShell or FormWindow. 

To create a window, the client allocates a window.Object using New, initializes it using 
Initialize, and presents it to Window for use using InsertlntoTree. When the window is of 
no further use, it is withdrawn from Window using RemoveFromTree, and the storage is 
freed using Free or FreeTree. 

New: procedure [ 

under, cookie, color: boolean false, zone: uncounted zone ^ nil] returns [Handle]; 

New allocates a window object. If zone is nil, a cache of objects is used. A client should 
never call zone. NEw[window. Object] because the window object will not be properly 
initialized. 

Initialize, InitializeWindow: procedure [ 

window: Handle, display: DisplayProc, box: Box, 
parent: Handle <— rootWindow, sibling, child: Handle <— nil, 
clearingRequired: boolean <-true, windowPane: boolean <- false, 
under, cookie, color: boolean <- false]; 

DisplayProc: type = procedure [window: Handle]; 

Initialize and InitializeWindow initialize the window object at window | . This must be 
done before the window is inserted into the window tree. The window is initially not a part 
of the window tree. The window may be created as an isolated window or may be linked to 
other private windows to form a private tree, display is the client procedure for repainting 
the window, box is the window's size and parent-relative location, parent is the window's 
parent, sibling is the sibling immediately below the window in the sibling stack of parent 
and child is the top child of the window, parent, sibling, and child may be nil. 
clearingRequired is described in §50.1.3. windowPane is described in §50.1.4. under 
indicates that the window can be associated with a bitmap-under. cookie and color are not 
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supported in the current release; clients should default this parameter for compatibility 
with future versions. 




Create: procedure [ 

display: OisplayProc, box: Box, 

parent: Handle «- rootWindow, sibling, child: Handle <<— nil, 
clearingRequired: boolean <-true, windowPane: boolean false, 
under, cookie, color: boolean <- false, zone: uncounted zone <- nil] 
RETURNS [Handle] s inline 

Create is an inline that follows a call to New with a call to Initialize. 

Free: procedure [window: Handle, zone: uncounted zone <- nil]; 

Free frees a window object. If zone is nil, the window is returned to the cache of objects 
maintained by Window; otherwise it is freed to the zone. Any contexts associated with the 
window, via the Context interface, are not freed. Free may raise Error[invalidParameters] 
if the window had already been freed, if the window is still in the window tree, if the zone 
is NIL but was not nil on the call to New, or the if zone is non-NiL but was nil on the call to 
New. 

FreeTree: procedure [window: Handle, zone: uncounted zone «- nil]; 

FreeTree frees the window and all its children, children first, and frees all contexts on 
windows in the subtree whose root is window.. Clients should almost always call FreeTree 
rather than Free. FreeTree may raise Error[invalidParameters] if the windows had already 
been freed, if the windows are still in the window tree, if the zone is nil but was not nil 
when the windows were allocated, or if the zone is non-NiL but was nil when the windows 
were allocated. FreeTree assume all the windows were allocated with the same zone if it is 
non-NiL. 

Caution: In the current version of ViewPoint, a window may be referred to for a few 
seconds after it is removed from the tree (due to another process simultaneously doing a 
Validate). Thus storage for Objects should not be freed immediately. 

50.2.3 Access to and Modification of a Window's Properties 

The Get procedures below return properties of a window. The Set procedures change 
properties and return the previous value. These properties of a window are described in 
this chapter's overview. 

GetOisplayProc: procedure [Handle] returns [DisplayProc]; 

SetDisplayProc: procedure [Handle, DisplayProc] returns [DisplayProc]; 

GetClearingRequired: procedure [Handle] returns [boolean]; 

SetClearingRequired: procedure [window: Handle, required: boolean] 
returns [old: boolean]; 

GetParent: procedure [Handle] returns [Handle]; 
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GetSibling: procedure [Handle] returns [Handle]; 

GetSiblIng returns the next lower sibling of the argument window. 

GetChild: procedure [Handle] returns [Handle]; 

GetChild returns the topmost child of the argument window. 

See also §50.2.4 for Set procedures that change a window's links to its parent, siblings, and 
child. 

EntireBox: procedure [Handle] returns [Box]; 

EntireBox returns the box [[0, 0], window.dims]. It is handy for invalidating the entire 
window. 

GetBox: procedure [Handle] returns [Box]; 

Note that there is no SetBox; SlideAndSize should be used instead. 
GetPane: procedure [Handle] returns [boolean]; 

GetPane returns whether or not the window is a window pane. The window pane property 
can only be set when the window is initialized. 

IsCookieVariant: procedure [Handle] returns [boolean]; 

Cookie cutters are not supported by the current release. IsCookieVariant should always 
return FALSE. 

IsColorVariant: procedure [Handle] returns [boolean]; 

Color is not supported by the current release. IsColorVariant should always return false. 

50.2,4 Window Tree and Window Box Manipulation 

Basic operations are provided for constructing private trees from private windows and for 
inserting them into and removing them from the window tree. Other operations allow 
moving a window within a window tree and changing a window's location and size. Special 
operations are provided to perform common combinations of these operations. 

Most clients obtain windows from some higher-level facilitiy like Form Window; in such 
cases, the window will typically have been already inserted into the window tree. Thus 
most clients will only use the following operations; Stack, Slide, SlideAndStack, 
SlideAndSize, SlideAndSizeAndStack. 

Unless otherwise noted, all of these operations may be applied either to windows in the 
window tree or to windows in a private tree. Operations performed on windows in private 
trees change tree links and the window's box, but naturally create no invalid regions on 
the display. 
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As described in the overview, none of the operations in this section perform screen 
painting. They merely enqueue painting work to be performed by a later Validate 
operation. 

IsDescendantOfRoot: procedure [Handle] returns [boolean]; 

IsDescendantOfRoot returns TRUE if window is currently a part of the window tree. 
ObscuredBySiblIng: procedure [Handle] returns [boolean]; 

ObscuredBySibling returns true if the box of any higher sibling intersects window's box. 

EnumerateTree: procedure [root: Handle, proc: procedure [window: Handle]]; 

EnumerateTree calls proc for every window in the tree rooted at root. The order of 
enumeration is not specified. Altering the tree while an enumeration is in progress will 
cause unpredictable operation. 

The following three operations allow constructing private trees from private windows. 

SetParent: procedure [window, newParent: Handle] returns [oidParent: Handle]; 

SetSibling: procedure [window, newSibling: Handle] returns [oldSibling: Handle]; 

SetChild: procedure [window, newChild: Handle] returns [oldChild: Handle]; 

These Set procedures set the parent, next lower sibling, or topmost child of window. No 
list manipulation nor consistency checking is done-these operations merely store their 
argument into the window object. If window is in the window tree, Error[windowlnTree] 
is raised (Stack, et al. can be used in that case). If inconsistent calls to the Set procedures 
are made, Error[windowNotChildO"fParent] will be raised when some subsequent 
operation detects the inconsistency. 

InsertlntoTree: procedure [window: Handle]; 

InsertlntoTree inserts a private window or subtree into any window tree, window will be 
inserted as a child of window. parent, window will be immediately above window. sibling 
in the sibling stack of the new parent; window. sibling = nil makes it be the bottommost 
sibling, window.child is the topmost child of a private tree that descends from the 
window-NiL if none. All of these fields of window may be set using the Set procedures 
described above. The client can force painting of the windows just inserted by doing 
window.GetParent[].ValidateTree[]. Error[noSuchSibling] may be raised. Fine Point: 

InsertlntoTree does not normally cause any painting activity. However, if a window that has a bitmap-under is 
inserted into the tree and the content of the bitmap is not available on the display, ValidateTree will be done on 
that window's parent to obtain the content of the bitmap. 

RemoveFromlree: procedure [Handle]; 

RemoveFromTree removes the window and all of its descendents from its containing tree. 
The window becomes the property of the client. The descendents of the window remain 
attached to it. The entire subtree may be later inserted back into a tree using 
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InsertlntoTree. The client can force painting of now-incorrect areas of the display by by 
applying ValidateTree to any parent of the removed window. 

Stack: procedure [window: Handle, newSibling: Handle, newParent: Handle «- nil]; 

Stack changes window's location in its window tree, thus changing the window's depth in 
the apparent stack of windows on the screen, If newParent is not NIL, then window is 
moved to be a child of newParent; otherwise, its parent is unchanged. Next, the sibling 
stack then containing window is modified so that window is now immediately above 
newSibling, thus potentially obscuring siblings lower on its sibling stack. Supplying 
newSibling = nil puts window on the bottom of the sibling stack. Unless window is 
already the top sibling, supplying newSibling = window. GetParent.GetChild[] puts 
window on the top of the stack. Caution: If window is the top sibling, the previous 
expression is a client error that is not guarded against. If one of window or newParent is 
in the window tree but the other is not, Error[illegalStack] is raised. Error[noSuchSibling] 
may also be raised. 

Slide: procedure [window: Handle, newPlace: Place]; 

Slide changes window's position relative to its parent. This procedure may be used to 
implement scrolling. Error[whosSlidingRoot] may be raised. 

SlideAndStack: procedure [ 

window: Handle, newPlace: Place, newSibling: Handle, newParent: Handle <— nil]; 

SlideAndStack performs a Stack and then a Slide, thus changing window's location in its 
tree and its position within its new parent. Error[illegalStack], Error[noSuchSibling], and 
Error[whosSlidingRoot] may be raised. 

Gravity: type ■= {nil, nw, n, ne, e, se, s, sw, w, c, xxx}; 

Gravity indicates where the old pixel content of a window should go when it changes size. 
This allows Window to reuse any current window content that will be visible in its new 
configuration. 

nil the contents remain at their current screen position (not 

their window-relative position). 

nw, n, ne, e, se, s, sw, w the contents stay attached to the indicated compass point of 

the window, which is either a corner or the middle of a side; 
for example, nw means the contents stay in the upper-left 
corner. 

c the contents go in the middle of the new window-trimming 

or expansion occurs equally at opposite edges. 

xxx the contents are discarded. 

SiideAndSize: procedure [window; Handle, newBox: Box, gravity: Gravity nw]; 

SlideAndSize changes both the location and size of window, gravity indicates what to do 
with the current contents of the window. Error[sizingWithBitmapUnder] and 
Error[whosSlidingRoot] may be raised. 
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SiideAndSizeAndStack: procedure [ 

window: Handle, newBox: Box, newSibiing: Handle, newParent: Handle <~ NIL, 
gravity: Gravity nw]; 

SiideAndSizeAndStack performs a Stack and then a SlideAndSize, thus changing 
window's location in its window tree and its position and size within its new parent. 
ErrorfillegalStack], Error[noSuchSibling], Error[sizingWithBitmapUnder], and 
Error[whosSlidingRoot] may be raised. 

Slideiconically: procedure [window: Handle, newPlace: Place]; 
Siidekonically is not implemented in the current release. 

30.2.5 Causing Painting 

A general description of painting is given in §50.1.3. The procedures below are used to 
cause areas of the screen to be painted, and in actually doing the painting 

InvalidateBox: procedure [window: Handle, box: Box, clarity: Clarity isDirty]; 

Clarity: type = {isClean, isDirty}; 

InvalidateBox declares that the current screen content of box in window is incorrect. 
Window adds box to the list of invalid regions of the window, clarity indicates the current 
state of the box. clarity = isClean means the region is already erased (all white); isDirty, 
that it contains some black. Window uses this information to avoid unnecessary clearing. 
InvalidateBox does not cause immediate display painting; only the Validate procedures do 
that. Note that a call on InvalidateBox followed by a call on Validate may result in no call 
to the display procedure-for example, if the invalidated area is not visible. If the window is 
not in the window tree, this operation does nothing. 

Validate: procedure [window: Handle]; 

ValidateTree: procedure [window: Handle <i- rootWindow]; 

Validate and ValidateTree are the only Window procedures that cause immediate display 

painting. Fine Point: The few special cases that do not follow this rule are noted in the text. Validate actS 

only on window; ValidateTree acts on the tree whose root is window. Typically, a client 
will update its data structures and invalidate various regions. When the client is ready to 
have the display updated, one of the Validate procedures is called. If window is not in the 
window tree, this operation does nothing. 

EnumeratelnvalidBoxes: procedure [window: Handle, proc: procedure [Handle, Box]]; 

EnumeratelnvalidBoxes is used within a window's display procedure to obtain the list of 
invalid regions of the window. EnumeratelnvalidBoxes calls proc for each of the invalid 
boxes of window; window is passed to proc as its first argument. The second argument of 
proc describes the region that is invalid. Note: A display procedure need not worry about 
redundant painting outside the invalid regions; Window automatically discards the 
display procedure's paint that falls outside the invalid regions. This operation must only 
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be called from within a display procedure, and window must be the window argument of 
the display procedure. 

FreeBadPhosphorList: procedure [window; Handle]; 

In special circumstances, a display procedure may wish to paint into valid visible areas. 
FreeBadPhosphorList deletes the display procedure's invalid area list; for the lifetime of 
that invocation of that display procedure, paint requests will be clipped only to the visible 
parts of the window. This operation must only be called from within a display procedure, 
and window must be the window argument of the display procedure. 

TrimBoxStickouts: procedure [window: Handle, box: Box] returns [Box]; 

TrimBoxStickouts returns a box which is the result of excluding any portion of box that 
sticks out of window or its ancestors. Display procedures may find it useful. 



50.2.6 Errors 



Error: error [code: ErrorCode]; 

ErrorCode: type = { 

iilegalBitmap, illegalFloat, windowNotChildOfParent, whosSlidingRoot, 
noSuchSibling, noUnderVarlant, windowlnTree, sizingWithBitmapUnder, 
illegalStack, invalidParameter}; 

iilegalBitmap A window passed to SetBitmapUnder is not totally visible. 

illegalFloat See Float. 



WindowNotChildOfParent 

whosSlidingRoot 

noSuchSibiing 

noUnderVariant 

windowlnTree 

SizingWithBitmapUnder 

illegalStack 



A window is not in the list of its parent's children. This 
usually means that inconsistent calls to SetParent, 
SetChild, or SetSibling were made. 

The client has attempted to move the root window. 

An operation moving a window in the window tree 
specifies a new sibling that is not a child of the new parent. 
A bitmap-under operation was applied to a window that 
may not have a bitmap-under associated with it. 

SetParent, SetSibling, or SetChild was applied to a window 
in the window tree. Stack, et al., can be used instead. 

A client has tried to change the size of a window that 
currently has a bitmap-under. 

The client is attempting to move a window between 
parents, one of which is in the window tree and the other is 
not. 
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invaiidParameter The client has invoked an operation with invalid 

parameters. 

50.2.7 Special Topic: Bitmap-Under 



Bitmap-unders are described in §50.1.4. Most clients have no need for bitmap-unders. 
IsBitmapUnderVariant: procedure [Handle] returns [boolean]; 

isBitmapUnderVariant returns true if the window can be associated with a bitmap-under 
(i.e., lnitializeWindow[ . . . , under: true]. 

WordsForBitmapUnder: procedure [window: Handle] returns [cardinal]; 

WordsForBltmapUnder returns the number of words of storage needed for a bitmap-under 
corresponding to the current size of window. 

SetBitmapUnder: procedure [ 

window: Handle, pointer: long pointer <— nil, 
underChanged: UnderChangedProc <— nil, 

mouseTransformer: MouseTransformerProc <-nil] returns [long pointer]; 
UnderChangedProc: type = procedure [Handle, Box]; 

MouseTransformerProc: type a procedure [Handle, Place] returns [Handle, Place]; 

I ) 

SetBitmapUnder associates a bitmap-under with window, pointer describes a scratch 
storage area for the bitmap-under; its length must be as given by WordsForBitmapUnder 
If pointer = nil, the window ceases to have a bitmap-under. The pointer to any previous 
bitmap-under is returned; the client becomes the owner of that storage. The 
underChanged and mouseTransformer parameters are ignored in the current release. If 
the window cannot be associated with a bitmap-under, Error[noUnderVariant] is raised. If 
the window is in the window tree but is obscured by another window, Error[illegalBitmap]! 
is raised. While the bitmap-under is in effect, the window's size cannot be changed; an 
attempt to do so will raise Error[sizingWithBitmapUnder]. 

GetBltmapUnder: procedure [window: Handle] returns [long pointer]; 

GetBitmapUnder returns the pointer to the current bitmap-under for window-returns nil 
if none. If the window cannot be associated with a bitmap-under, Error[noUnderVariant]| 
is raised. 



Float: procedure [window, temp: Handle, proc: FloatProc]; 

FloatProc: type = procedure [window: Handle] returns [place: Place, done: boolean]; 

Float is used to move a window continuously on the screen. Float first forces window to the 
top of its sibling stack, next does ValidateTree[rootWindow], and then enters a loop for 
changing the window's position. In the loop, Float calls proc, passing window to it. If proc 
returns done ■ true, the operation terminates and Float returns to the client. Otherwise, 
Float moves the window to place and repaints the display-and does so without calling any 
client display procedure; control returns to the top of the loop. The client must ensure that 
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the window is wholly visible when moved to place, temp is used for temporary storage for 
the duration of the float operation, temp must be the same size as window, have a bitmap- 
under, and not be in the window tree. If window is not in the window tree, if temp is in the 
window tree, if either window lacks a bitmap-under, or |f the windows have different sizes, 
Error[illegalFloat] is raised. 

50.3 Usage/Examples 

A scrollbar is an example of a simple window. An entire StarWindowShell window is an 
example of a window that has many descendant windows— the window header, the 
scrollbars, and the main interior window used to display the content. 

Window shields the client from interference between windows and from the presence of 
the edges of the display screen. A client can freely move a window around on or off the 
screen and alter its position in the stack of windows; Window automatically handles the 
overlapping. 

Window automatically clips painting into windows to the visible interior of its parent 
window. A client can freely paint anywhere inside or even outside of its window as 
convenient. 



It is always correct to paint more of a window than the minimum required. Simple clients 
may adopt a simple repaint strategy, invalidating and/or repainting a large part or even 
all of a window. Sophisticated clients may invalidate only the necessary parts of a window, 
thus allowing only small amounts of repainting and minimizing references to the 
window's backing data. This may result in improved performance. 

A display procedure has available to it a list of invalid areas that need to be repainted. 
However, it may adopt the simple approach of ignoring this data and repainting the entire 
window. In any case, Window clips a display procedure's paint to the boundaries of the 
invalid regions. 

Areas that project outside of a window's parent are trimmed for display purposes. Vertical 
scrolling can be implemented quite simply by embedding a tall content window in a short 
clipping window and then just Slideing the position of the content window within the 
clipping window. Horizontal scrolling can be done in a similar way. The StarWindowShell 
interface supports this method of scrolling. This approach is limited by the domain of the 
coordinates, which are integers. Scrolling in this manner is limited to 4--2t 15 pixels 
offset from the frame window. If more scrolling than this is required, the client cannot use 
this technique, but must itself perform the transformation from data coordinates to 
window coordinates. 

Since a window's location is defined in its parent window's coordinate system, moving a 
window automatically moves all of its descendant windows along with it. 

Window itself has nothing to do with the keyboard and mouse. However, the TIP interface 
provides the facility for associating mouse and keyboard actions with a window. 



50.3.1 Display Procedures and moniitors 

Any process may manipulate windows, and thus cause screen painting activity. Even if 
one client always runs in the Notifier process, its window's display procedure may be 
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called at any instant because of asynchronous activities by some other process. // a 
window's display procedure uses any nonlocal variables in its painting activity (the usual 
case), those variables must be protected by a MONITOR. Most display procedures are monitor 
entry procedures. Of course, if the display procedure only refers to immutable data, its 
operation need not be monitored. 

Since a display procedure is usually a monitor entry, the client must avoid deadlocks by 
not invoking the display procedure from within other monitor procedures. This is the 
standard rule for monitors. Because calling Validate may cause Window to call the 
client's display procedure, calls to Validate must be done outside the client's monitor. The 
normal arrangement is (1) enter monitor, (2) update monitor data and Invalidate regions, 
(3) exit monitor, (4) Validate (which causes the display to be repainted). 

50.3.2 Example 

— These excerpts are taken from <BWSHacks> 1 .0> Source> PuzzletSlmpl.mesa 

boxSize: CARDINAL = 32; 

boxDims: Window. Dims » [boxSize, boxSize]; 

bodyWindowDims: window.Dims = [boxSize*grid + 2, boxSize*grid + 2]; 
boxes: ARRAY [0..max) OF window. Box; 

MenuProc: MenuData.MenuProc a { 

another: xstring.ReaderBody «- xstring.FromSTRING["Another"Ll; 
rb: xstring.ReaderBody *- xstring.FromSTRING["1 5 Puzzle"L]; 
shell: starwindowsheii. Handle = starwindowSheii.Create [name: @rbl; 
-- Window.lnitializeO is called by StarWIndowShell Impls. 
body: window. Handle = starwindowSheil.CreateBody [ 
sws: shell, 

box: [[0,0],bodyWindowDims], 
repaintProc: Redisplay, 
bodyNotifyProc: NotifyProc ]; 



starwindowSheii.SetRegularCommands [shell, myMenul; 
starWindowSheli.SetPreferredDims [shell, bodyWindowDims]; 
starwindowSheii.SetPreferredPlace [shell, [200, 200]]; 
StarWindow Shell. Push [shell]; 

}; 

NotifyProc: TiP.NotifyProc = { 

data: Data LocalFind[window]; 
place: window. Place; 

FOR input: TiP.Results<— results, input.next UNTIL input « nil do 
WITH z: input select from 
coords a > place «-z. place; 

atom a > SELECT Z.a FROM 

pointUp as > { 

box: CARDINAL ResolveToBox [place]; 
IF Adjacent [data. empty, box] then { 
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Window.! nvalidateBox [window, boxes[data.empty]]; 
window.lnvalidateBox [window, boxes[box]]; 
SwapBoxWithEmpty [data, box]; 
window.Validate[window]; 

}; 

}; 

endcase; 
enocase; 



Redisplay: proc [window: window.Handle] a { 

— This is the body window's display procedure. 
data: Data Local Find [window] ; 

vertical: Window. Dims [2, boxSize*grid]; 
horizontal: window. Dims [boxSize*grid, 2]; 
place: window.Place [0,0]; 
— Display the 15 numbers 
FOR i: CARDINAL IN [0..max) DO 

value: cardinal data.values[i]; 

Display.Bitmap [window, boxes[i], [@bitmaps[value],0,0], boxSize]; 

ENDLOOP; 

— Display the vertical lines 

FOR i : CARDINAL IN [0..grid + 2) DO 

Display.Black [window, [place,vertical]]; 
place.x place. X + boxSize; 

ENDLOOP; 

" Display the horizontal lines 
places- [0,0]; 

FOR i : CARDINAL IN [0..grid 2) DO 

Display.Black [window, [place,horizontal]]; 
place.y ^ place.y + boxSize; 

ENDLOOP; 

}; 

Init: PROC = { 

rb: xstring.ReaderBody «-xstring.FromSTRING["15 Puzzle"L]; 
starDesittop.AddltemToAttentionWindowMenu [ 
MenuOata.Createitem [ 

zone: Heap.systemZone, 

name: @rb, 

proc: MenuProc] ]; 



}; 
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50.4 Index of Interface Items 



Item 


Page 


Item 


Page 


BitmapPlace: procedure 


5 


IsBitmapUnderVariant: procedure 


12 


BitmapPlaceToWindowAndPlace: procedure 5 


IsCookieVariant: procedure 


7 


Box: TYPE 


4 


IsColorVariant: procedure 


7 


BoxesAreDisjoint: procedure 


4 


IsDescendantOfRoot: procedure 


8 


BoxHandle: type 


4 


IsPlacelnBox: procedure 


5 


Clarity: type 


10 


MinusLandBitmapUnder: type 


4 


Create: procedure 


5 


MinusLandColor: type 


4 


Dims: type 


4 


MinusLandCookieCutter: type 


4 


DisplayProc: type 


5 


MouseTransformerProc: type 


12 


EntireBox: procedure 


7 


New: procedure 


5 


EnumeratelnvalidBoxes: procedure 


10 


nullBox: Box 


4 


EnumerateTree: procedure 


8 


Object: type 


3 


Error: error 


11 


ObscuredBySibling: procedure 


8 


ErrorCode: type 


11 


Place: type 


4 


Float: procedure 


12 


RemoveFromTree: procedure 


8 


FloatProc: procedure 


12 


Root: procedure 


4 


Free:PROCEDURE 


6 


rootWindow: variable 


4 


FreeBadPhosphorList: procedure 


11 


SetBitmapUnder: procedure 


12 


FreeTree: PROCEDURE 


6 


SetChild: procedure 


8 


GetBitmapUnder: procedure 


12 


SetClearingRequired: procedure 


6 


GetBox: procedure 


7 


SetDlsplayProc: procedure 


6 


GetChild: procedure 


7 


SetParent: procedure 


8 


GetClearingRequired: procedure 


6 


SetSibling: procedure 


8 


GetDisplayProc: procedure 


6 


Slide: procedure 


9 


GetPane: procedure 


7 


SlideAndSize: procedure 


9 


GetParent: procedure 


6 


SlideAndSizeAndStack: procedure 


10 


GetSibling: procedure 


7 


SlideAndStack: procedure 


9 


Gravity: type 


9 


Slidelconically: procedure 


10 


Handle: type 


3 


Stack: procedure 


9 


Initialize: procedure 


5 


TrimBoxStickouts: procedure 


11 


InitializeWindow: procedure 


5 


UnderChangedProc: type 


12 


InsertlntoTree: procedure 


8 


Validate: procedure 


10 


IntersectBoxes: procedure 


4 


ValidateTree: procedure 


10 


InvaiidateBox: procedure 


10 


WordsForBitmapUnder: procedure 


12 
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51.1 Overview 

The XChar interface is part of a string package that supports the Xerox Character Code 
Standard, referred to in this document as the "standard." XChar defines the basic 
character type and some operations on it. 

The standard defines 16-bit characters, which would permit up to 65,536 distinct 
characters. Reserving control character space reduces them to 35,532. It is convenient to 
partition the character code range into 256 blocks of 256 codes each. Each block is called a 
'^^^^ character set. This approach allows a convenient run-encoding scheme. 

All of the character sets currently defined are enumerated in XCharSets. 

51.2 Interface Items 

51.2.1 Character Representation 
Character: type ■ word; 
Character is a 16-bit character. 

Fine Point: Currently only 16-bit characters are defined by the standard, but larger characters are not precluded. 
If the standard is extended to include more bits per character, the type Character will have to be redefined. 

CharRep: type = machine dependent record [set, code: Environment.Byte]; 

CharRep is a type that defines the representation of a character as character set and code. 
The operations Code, Make, and Set should be used instead of this type. 

Code: procedure [c: Character] returns [code: Environment.Byte] ; 

Code returns the code within a character set of the character parameter. 

Make: procedure [set, code: Environment.Byte] RETURNS [Character]; 
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Make constructs a character, given a character set and a code within the character set. 
Set: PROCEDURE [c: Character] returns [set: Environment. Byte] ; 

Set returns the character set of the character parameter. 

null: Character = 0; 

not: Character » 177777B; 

not is a value that may be used by operations that return a character to signify that no 
characters remain. 

51.2.2 JoinDirection and StreakNature 

JoinDirection: TYPE = {nextCharToLeft, nextCharToRight}; 

JoinDirection specifies whether a character goes left to right or right to left. 

GetloinDirection: procedure [Character] returns [JoinDirection]; 

GetloinDirection returns the join direction for a character, given its set and code within its 
set. 

ArabicFirstRightToLeftCharCode: Environment.Byte = 60B; 
ArabicFirstRightToLeftCharCode is used by GetloinDirection. 
StreakNature: type * {leftToRight, rightToLeft}; 
GetStreakNature: procedure [Character] returns [StreakNature]; 
Returns a characters StreakNature (see SimpieTextDisplay.StreakSuccession). 

51.2.3 Case 

Decase: procedure [c: Character] returns [Character]; 

Decase is a case-stripping operation. It returns c with all case information removed. This 
is useful when comparing characters with case ignored. Only characters in character sets 
zero (Latin), 46(Greek), and 47(Cyrillic) are affected. 

Lowercase: procedure [c: Character] returns [Character]; 

LowerCase returns the lowercase representation of character c. Only characters in 
character set zero (Latin), 46 (Greek), and 47 (Cyrillic) are affected. 

Uppercase: procedure [c: Character] returns [Character]; 

Uppercase returns the uppercase representation of character c. Only characters in 
character set zero (Latin), 46 (Greek), and 47 (Cyrillic) are affected. 
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51.3 Usage/Examples 

The following two examples create specific characters. xchar.Make is also useful if the 
character set and code are not known at compile time, but are known at run time. 

51.3.1 Creating an ASCII Character 

The following example creates an ASCII CR character. 

c: xchar.Character«-xchar.Make(set: xcharSets.Sets.latln.ORD, code:LOOPHOLE[Ascli.CR]]; 

51.3.2 Creating a Greek Character 

The following example creates a a from the Greek character set. 

c: xchar.Character <-xchar.Make[set:xcharSet$.Sets.greek.ORD, code: 
xcharSet46.Codes46.iowerAlpha.ORD]; 
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51.4 Index of Interface Items 
Item 

ArabicFirstRightToLeftCharCode: type 
Character: type 
CharRep: type 
Code: procedure 
Decase: procedure 
GetloinDirection: procedure 
GetStreakNature: procedure 
JoinDirection: type 
Lowercase: procedure 
Make: procedure 
null: TYPE 
not: TYPE 

Set: PROCEDURE 

StreakNature: type 
Uppercase: procedure 





Page 

2 
1 
1 
1 
2 
2 
2 
2 
2 
1 
2 
2 
2 
2 
2 
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52.1 Overview 

XCharSets enumerates the character sets defined in the Xerox Character Code Standard. 
This chapter also describes a collection of interfaces that enumerate the character codes of 
several common character sets. This collection of interfaces is XCharSetNNN. 

52.2 Interface Items 

52.2.1 Sets * 

Sets: TYPE = MACHINE DEPENDENT { 

latin(0),firstUnused1(1), lastUnused1(40B), jisSymbol1(41B), jisSymbol2(42B), 
extendedLatin(43B), hiragana(44B), katakana(45B), greek(46B), cyrillic(47B), 
firstUserKanji1(50B), lastUserKanji1(57B), firstLevel1Kanji(60B), 
lastLevel1Kanji(117BKfirstLevei2Kanji(120B), lastLevel2Kanji(163B), jSymbol3(164B), 
firstUserKanji2(165B)JastUserKanji2(176B),firstUnused2(177B),lastUnused2(240B), 
firstReserved1(241B), lastReserved1(337B),arabic(340B), hebrew(341B), 
firstReserved2(342B), lastReserved2(355B), generalSymbols2(356B), 
generalSymbols1(357B), firstRendering(360B), lastRendering(375B), 
userDefined(376B), selectCode{377B)}; 

Sets enumerates the character sets. Specific character sets have values defined, such as 
Latin and Hiragana. Character set families such as Kanji and unused or reserved portions 
of the character set enumeration are specified by first and last values; for example, 
firstUserKanjil and lastUserKanjil. 

For those eleven character sets whose codes are specified in the standard, an interface has 
been defined that contains an enumerated type enumerating the codes within the 
character set and a Make procedure that will make a character given a code literal. 

For example, the interface XCharSet356 has the following definitions: 

Make: procedure [code: Codes356] returns [Character]; 
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Codes356: TYPE s machine dependent { 

thickSpace(41 B), fourEmSpace(42B), hairSpace(43B), punctuationSpace(44B), 
decimaiPoint(56B), absoiuteVaiue(174B), simiiarTo(176B), escape(377B)}; 

52.2.2 Enumeration of Character Sets 

Table 52.1 enumerates the eleven character sets whose codes are specified in the standard, 
the interface in which they are contained, and the enumerated type name for that 
interface. 



Character Set 


Interface 


Enumerated Type 


Latin 


XCharSetO 


CodesO 


jisSymboM 


XCharSet41 


Codes41 


jisSymbol2 


XCharSet42 


Codes42 


extended Latin 


XCharSet43 


Codes43 


Hiragana 


XCharSet44 


Codes44 


Katakana 


XCharSet45 


Codes45 


Greek 


XCharSet46 


Codes46 


Cyrillic 


XCharSet47 


Codes47 


jSymbolB 


XCharSet164 


Codes 164 


generalSymbols2 


XCharSet356 


Codes356 


generalSymbolsl 


XCharSet357 


Codes357 



Table 52. 1 : Standard Character Sets 

52.3 Usage/Examples 

52.3.1 Creating a Greek Character 

The following example shows two ways to create an a from the Greek character set. 

c: xchar.Character <-xchar.Make[set:xcharSets.Sets.greek.ORD, code: 
xcharSet46.Codes46.lowerAlpha.0RDl; 

C: XChar.Character ♦-XCharSet46.Makelcode: XCharSet46.Codes46.lowerAlpha.ORDl; 
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52.4 Index of Interface Items 

Item Page 

Code$356: type 2 
Make: procedure 1 
Sets: TYPE 1 
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53.1 Overview 

This interface assigns the global handle and message keys for all the messages the system 
requires for system templates (such as time and date formatting, numbers, etc.). The 
XMessage interface deals with system messages; it must be understood before using this 
interface. 

53.2 Interface Items 

53.2.1 Obtaining Message Handle 

GetHandle: procedure returns [h: xMessage.Handle]; 

This procedure returns a handle for system-required messages that have already been 
initialized and allocated, and registered by the XComSoftMessage implementation. 

53.2.2 Message Keys 

Keys: type = machine dependent { 

time(O), date(1), dateAnclTime(2). am(3), pm(4), january(5), february(6), march(7), 
april(8), may(9), june(IO), july(ll), august(12), september(13), october(14), 
november(15), december(16), monday(17), tuesday(18), wednesday(19), 
thursday(20), friday(21), saturday(22), sunday(23), decimalSeparator(24), 
thousandsSeparator(25)}; 

time, date, and dateAndTime are available through the XTime interface; they may be 
used as templates in calls to XTime.ParseReader or XTime.Append. 

Months: type = Keys [January. .december]; 

DaysOfWeek: type = Keys [monday.. Sunday]; 
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53.3 Usage/Examples 

OPEN XCSM: XComSoftMessage; 

systemMsgs: XMessage. Handle <-xcsM.GetHandle []; 
mondayString: xstring. Reader <—XMessage. Get [ 
systemMsgs, xcsM.DaysOfWeek.monday.ORD]; 
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53.4 Index of Interface Items 

Item Page 

GetHandle: procedure 1 

Keys: type 1 

Months: type 1 

OaysOfWeek: type 1 
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54.1 Overview 

The XFormat package provides procedures for formatting various types into 
xstring. Readers. The procedures require the client to supply an output procedure and a 
piece of data to be formatted. Where appropriate, a format specification is also required. 

54.1.1 Major Data Structures 

The major data structure is the Handle, which points to an object containirig a FormatProc, 
an xstring.Context.and some ClientData. All the formatting operations take a handle as 
the destination of the formatted character string. The FormatProc is the main component 
of an Object. It should pass the characters of its reader parameter to the output sink it 
implements and update the object's context to reflect the context of the last character of 
the reader parameter. 

The other major data structure is the NumberFormat, which defines how numbers are to 
be converted to text strings. It includes the base of the number, the number of columns the 
text string should contain, whether to treat the number as signed or unsigned, and 
whether to fill leading columns with zeros or spaces. 

A FormatProc is the destination of all output from the format routines. It is the main 
component of an Object. It should pass the characters of r to the appropriate sink and 
update h. context to reflect the context of the last character of r. 

54.1.2 Operations 

There are two major classes of operations in XFormat. The first class is used to format 
various data types and pass them to a format procedure. These operations contain simple 
text operations such as Blanks, Reader, and String; numeric operations such as Decimal 
and Number; network- related operations such as NetworkAddress and HostNumber;and 
some compatibility routines such as NSString. All these operations direct their output to 
the format procedure in their handle parameter. If this parameter is defaulted, it is 
directed to the default output sink. 



54-1 



54 



XFormat 



The second class of operations provide built-in format procedures that direct their output 
to the following well-known data types: xstring.Writer, stream. Handle, TTY.Handle,and 
Nsstring. String. 



Handle: TYPE » long pointer to Object; 

Object: type = record [ 
proc: FormatProc, 

context: xstnng.Context <— xstnng.vanillaContext, 
data: ClientData «— nil]; 

FormatProc:TYPE = procedure [r: xstring.Reader, h: Handle]; 

ClientData: TYPE a long pointer; 

A Handle is a parameter to all the formatting operations. Its object encapsulates the 
output sink that is the destination of all formatted text. The proc field is called one or more 
times for each formatting operation; it should pass the characters of its reader parameter 
to the output sink it implements. The context field is used to hold the context of the last 
character sent to the format procedure. It should be updated by the format procedure. The 
data field allows client-specific information to be passed to the format procedure. 



54.2.2 Default Output Sink 

SetDefauitOutputSink: procedure [new: Object] returns [old: Object]; 

SetDefaultOutputSink sets the default object that is the default destination for all 
formatted output. For each of the formatting operations, if the handle parameter is nil, it 
is directed to the default output sink. The default output sink is initialized to an object 
that ignores all results. 

54.2.3 Text Operations 



Blanks: procedure [h: Handle <- NIL, n: cardinal 1]; 

Blanks calls on h.proc with readers that contain a total of n blanks, h.proc may be called 
more than once. 

Block: procedure [h: Handle <- NIL, block: Environment.Blockj; 

Block calls on h.proc with a reader that contains the characters in block. 

Char: procedure [h: Handle <- NIL, char: xstring.Character]; 

Char calls on h.proc with a reader that contains only the character char. 



54.2 Interface Items 



54.2.1 Handles and Objects 
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CR: PROCEDURE [h: Handle <- NIL, n: cardinal 11; 

CR calls on h.proc with readers that contain a total of n carriage returns (15C). h.proc may 
be called more than once. 

Line: procedure [h: Handle NIL, r: xstring.Reader, n: cardinal 1]; 

Line calls on h.proc with r and then readers that contain a total of n carriage returns 
(15C). h.proc will be called more than once. 

Reader: procedure [h: Handle <- NIL, r: xstring.Reader]; 

Reader calls on h.proc with r. 

ReaderBody: procedure [h: Handle <- NIL, rb: xstring.Reader]; 

ReaderBody calls on h.proc with @rb. 

String: procedure [h: Handle NIL, s: long string]; 

String calls on h.proc with readers that contain the characters in s. 

54.2.4 Number Formats 

NumberFormat: type = record [base: [2..36] ^10, 

zerofill: boolean <~ false, signed: boolean «- false, columns: [0..255] 0 ]; 

NumberFormat is used by the number-formatting procedures. The number will be 
formatted in base base in a field at least columns wide (zero means "use as many as 
needed"). If zerofill is true, the extra columns are filled with zeros; otherwise, spaces are 
used. If signed is true and the number is less than zero, a minus sign preceeds all output, 
except for columns that are filled with spaces. For bases greater than 10, the characters 
'A..'Z are used as digits. 

DecimalFormat: NumberFormat = [ 

base: 10, zerofill: false, signed: true, columns: 0]; 

HexFormat: NumberFormat - [ 

base: 16, zerofill: false, signed: false, columns: 0]; 

OctalFormat: NumberFormat a [ 

base: 8, zerofill: false, signed: false, columns: 0]; 

UnsignedDecimalFormat: NumberFormat a [ 

base: 10, zerofill: false, signed: false, columns: 0]; 

These are useful number format constants. The output will fill as many columns as 
needed. 
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54.2.5 Numeric Operations 

Number: procedure [ 

h: Handle NIL, n: long unspecified, format: NumberFormatl; 

Number formats n to a string according to the number format format. The number will be 
formatted in base base in a field at least columns wide (zero means "use as many as 
needed"), [f zerofill is true, the extra columns are filled with zeros; otherwise, spaces are 
used. If signed is true and the number is less than zero, a minus sign preceeds all output, 
except for columns that are filled with spaces. For bases greater than 10, the characters 
'A..'Z are used as digits, h.proc will be called several times with pieces of the output as 
they are generated. 

Decimal: procedure [h: Handle <- NIL, n: long integer]; 

Decimal converts n to signed base 100. It is equivalent to Number[h, n, DecimalFormat]. 
Hex: procedure [h: Handle <- NIL, n: long cardinal]; 

Hex converts n to signed base 160. It is equivalent to Number[h, n, HexFormat]. 
Octal: procedure [h: Handle <- NIL, n: long unspecified]; 

Octal convert n to base 80. When n is greater than 7, the character 'B is appended. It is 
equivalent to Number[h, n, OctalFormat]; if n > 7 then Char[h, 'B.ordJ. 

34.2.6 Built-in Sinks 

The XFormat interface provides several built-in format procedures that know how to send 
output to particular destinations. For each of the four known types of destinations 
(xstring.Writer, stream. Handle, TTY. Handle, and NSStn'ng. String), there are both the format 
procedure as well as an operation that returns an object initialized with the appropriate 
format procedure and destination data. Both the format procedures and the object 
operations may raise the error Error[nilData] if the expected data is nil. 

NSStringProc: FormatProc; 

NSStringObject: procedure [s: long pointer to NSString.String] returns [Object]; 

NSStringProc appends the reader to an NSString.String. It expects h.data to be a long pointer 
to NSString.String. NSStringObject constructs an object whose proc is NSStringProc and 

whose data is s. 

StreamProc: FormatProc; 

StreamObject: procedure [sH: stream. Handle] returns [Object]; 

StreamProc puts the bytes of the reader to a stream. Handle. It expects h.data to be a 
stream. Handle. StreamObject constructs an object whose proc is StreamProc and whose 
data is sH. 
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TTYProc: FormatProc; 

TTYObject: procedure [h: TTY. Handle] returns [Object]; 

TTYProc puts the bytes of the reader to a TTY. Handle. It expects h.data to be a TTY. Handle. 
TTYObject constructs an object whose proc is TTYProc and whose data is h. 

WriterProc: FormatProc; 

WriterObject: procedure [w: XString.Writer] returns [Object]; 

WriterProc appends the reader to a XString.Writer. It expects h.data to be a XString.Writer. 
WriterObject constructs an object whose proc is WriterProc and whose data is w. 

54.2.7 Date Operation 

DateFormat: TYPE = {dateOnly, timeOnly, dateAndTime}; 

DateFormat allows the user to specify which template from XTime is used when the date is 
to be formatted by the procedure Date. 

Date: procedure [ 

h: Handle NIL, time: System. GreenwichMeanTime <— System. gmtEpoch, 
format: DateFormat <— dateAndTime]; 

Date converts time to a string by calling XTlme.Append, using format to specify which 
template to use. h.proc is then called. If time is defaulted, the current time is used. 

54.2.8 Network Data Operations 

NetFormat: type » {octal, hex, productSoftware}; 

NetFormat is used by the procedures that format network addresses, octal converts the 
number to octal, hex converts to hex, and productSoftware converts the item to a decimal 
number and then inserts a "-" every three characters, starting from the right. An example 
of a number in product software format is 4-294-967-295. 

HostNumber: procedure [ 

h: Handle NIL, hostNumber: System. HostNumber, format: NetFormat]; 

HostNumber calls on h.proc with a reader that contains hostNumber formatted as defined 
by format. 

NetworkAddress: procedure 

h: Handle NIL, networkAddress: System.NetworkAddress, format: NetFormat]; 

NetworkAddress calls on h.proc with a reader that contains networkAddress with the 
form network-numberi^host-number# socket-number, where the format of the various 
components isdetermined by format. 
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NetworkNumber: procedure [ 

h: Handle *— NIL, networkNumber: System.NetworkNumber, format: NetFormatl; 

NetworkNumber calls on h.proc with a reader that contains networkNumber formatted 
as defined by format. 

SocketNumber: procedure [ 

h: Handle <— NIL, socketNumber: System.SocketNumber, format: NetFormat]; 

SocketNumber calls on h.proc with a reader that contains socketNumber formatted as 
defined by format. 

34.2.9 NSString Operations 

NSChar: procedure [h: Handle <- NIL, char: NSString.Characterl; 

NSChar calls on h.proc with a reader that contains the character char. 

NSLine: procedure [h: Handle «- NIL, s: NSString.StrIng, n: cardinal 1]; 

NSLine calls on h.proc with a reader that contains the characters in s, then calls on 
readers that contain a total of n carriage returns (15C). h.proc may be called more than 
once. 

NSString: procedure [h: Handle *— NIL, s: NSString.String]; 

NSString calls on h.proc with a reader that contains the characters in s. 

54.2.10 Errors 

Error: error [code: ErrorCode] ; 
ErrorCode: type = {invalidFormat, nilData}; 

invalidFormat The term invalidFormat means an invalid operation has been 
attempted 

nilData The term nilData means h.data was nil, but the format procedures 

wanted valid data. 

54.3 Usage/Examples 

54.3.1 Using Built-in Sinks 

The XFormat interface allows clients to convert data types to their textual representation. 
By using the built-in sinks, clients can put this text into streams, tty. handle, and append 
to writers. In particular, although the XString interface does not include any append 
number operations, XFormat may be used to accomplish this task. 

AppendNumber: procedure [ 

w: xstring.Writer, n: long integer, format: xFormat.NumberFormatl = { 
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xfo: XFormat.Object <- XFormat.WriterObject(w]; 
XFormat.Number[h: @xfo, n: n, format: formatl}; 

54.3.2 Creating New Format Procedures 

While XFormat provides some useful output sinks, clients may wish to build new sinks. 
The following example hypothesizes a log window that can display text in a window and 
allows appending of text to the end. 

LogWindow: definitions a { 

Create: procedure [w: window. Handle, file: NSFiie.Handle]; 
Destroy: procedure [w: window.Handle]; 

LogReader: procedure [w:; window.Handle, r: xstHng.Reader]; 
Info: procedure [w: window.Handle] returns [ 

file: NSFile.Handie, nChars: long integer, endContext: xstring.Context]; 

LogFormatProc: XFormat.FormatProc; 

LogFormatObject: procedure [w: window.Handle] returns [object: XFormat.Object] 

ErrorCode: type = {notALog Window}; 

Error: Error [code: ErrorCode]; 

}.. 

LogWindowlmpi: PROGRAM » { 

Create: PUBUC procedure [w: Window.Handle, file: NSFile.Handie] a {...}; 
Destroy: PUBLIC procedure [w: Window.Handle] a {...}; 

LogReader: public procedure [w: window.Handle, r: xstHng.Reader] = {...}; 
Info: PUBLIC PROCEDURE [w: Window.Handle] returns [ 

file: NSFile.Handie, nChars: long integer, endContext: xstring.Context] = {...}; 

LogFormatProc: PUBLIC XFormat.FormatProc = { 
w: Window.Handle a h.data; 
iFw a NIL THEN error xFormat.Error[nilData]; 
LogReaderfw: w, r: r]; 
h. context lnfo[w]. endContext}; 

LogFormatObject: public procedure [ 

w: Window.Handle] returns [object: XFormat.Object] = { 
iFw a NIL THEN ERROR XFormat.Error[nilData]; 

RETURN|[proc: LogFormatProc, context: lnfo[w].endContext, data: w]]}; 

The bulk of the work is done in the LogReader procedure. It is assumed that the log 
window keeps track of the context of the end of the log so that it will add the necessary 
character set shift information when a reader that begins with a different character set is 
logged. If the log window didn't take care of this, the format procedure would have to set 
that itself, as the stream format procedure example below shows. 
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StreamProc: PUBLIC XFormat.FormatProc = { 
stream: stream. Han die » h.data; 
startsWith377B: boolean; 
c: xstring.Context; 

IF stream = nil then error XFormat.Error[nilData]; 
[context: c, startsWith377B: startsWith377B] ^-xstring.ReaderlnfoErl.- 
SELECTTRUE from 

startsWith377B = > null; 
c.suffixSize a 2 » > 

IF h.context.suffixSize = 1 then { 

stream. PutByte[377Bl; stream.PutByte[377Bl; stream. PutByte(0]}; 
h.context.suffixSize » 2, c.prefix # h.context.prefix ■ > { 

stream.PutByte[377B]; stream.PutByte[c.prefix]}; 
enocase; 

stream.PutBlock[block: xstring.Block[r]]; 

h. context <— xstring.ComputeEndContextfr]}; 
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54.4 Index of Interface Items 

Item Page 

Blanks: procedure 2 

Block: PROCEDURE 2 

Char: procedure 2 

ClientData: TYPE 2 

CR: procedure 3 

Date: procedure 5 

DateFormat: type 5 

Decimal: procedure 4 

DecimalFormat: NumberFormat 3 

Error: error 6 

ErrorCode:TYPE 6 

FormatProc: type 2 

Handle: TYPE 2 

Hex: PROCEDURE 4 

HexFormat: NumberFormat 3 

HostNumber: procedure 5 

Line: procedure 3 

NetFormat: type 5 

NetworkAddress: procedure 5 

NetworkNumber: procedure 6 

NSChar: procedure 6 

NSLine: procedure 6 

NSString: PROCEDURE 6 

NSStringObject: procedure 4 

NSStringProc: FormatProc 4 

Number: procedure 4 

NlimberFormat: type 3 

Object: type 2 

Octal: PROCEDURE 4 

OctalFormat: NumberFormat 3 

Reader: procedure 3 

ReaderBody: procedure 3 

SetDefaultOutputSInk: procedure 2 

SocketNumber: procedure 6 

StreamObject: procedure 4 

StreamProc: FormatProc 4 

String: PROCEDURE 3 

TTYObject: procedure 5 

TTYProc: FormatProc 5 

UnsignedDecimalFormat: NumberFormat 3 

WriterObject: procedure 5 

WriterProc: FormatProc 5 
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55.1 Overview 

XLReal supports manipulation of real numbers with greater precision than Mesa reals. 

55.2 Interface Items 

55.2.1 Representation 

^mp'^ Numbers are maintained as 13 decimal digits of signed mantissa with a 10-bit exponent 

(-512 to 511). All routines maintain the normalized numbers, i.e., the first digit is non- 
zero. The assumed decimal point is after the first digit. Numbers are stored as opaque 
objects occupying 4 words (64 bits). 

Digit: type = [0..91; 
Number: type [4]; 

Bits: TYPE = ARRAY [0..4) OF CARDINAL,' 

ValidExponent: type = [-512..5111; 

Digits: type = packed array [0..accuracy) of Digit; 

accuracy: NATURAL = 13; 

55.2.2 Conversion 

ReadNumber: procedure [ 

get: proc returns [xchar.Character], putback: proc [xchar.Character]] returns [Number]; 

ReaderToNumber: PR0CEDURE[r: xstring.Reader] returns [Number]; 

ReadNumber and ReaderToNumber may raise Error[overfiow]. 

NumberToPair: procedure [ 

n: Number, digits: [1.. accuracy]] returns [negative: boolean, exp: integer, mantissa: 
Digits]; 
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PairToNumber: procedure[ 

negative: boolean, exp:iNTEGER, mantissa: Digits] returns [n: Number]; 

In PairToNumber and NumberToPair, the decimal point, is between mantissa[01 and 
mantissa[l]. NumberToPair may raise Error(notANumber]. PairToNumber may raise 
Error[underflow]. 

IntegerPart, FractionPart: procedure [Number] returns [Number]; 

IntegerPart and FractionPart may raise ErrorfnotANumber]. FractionPart may also raise 
Error[overflow]. 

Fix:PR0CE0URE [Number] returns [long integer]; 
Float: PROCEDURE [long integer] returns [Number]; 

Fix may raise Error(notANumber] and Error[overflow]. 

FormatReal: procedure [h: XFormat.Handle <~ NIL, r: Number, width: natural]; 

FormatReal formats r into a field widtli elements wide and passes the resulting text to h. 

PictureReal: procedure [ 

h: XFormat.Handle <- NIL, r: Number, template: xstring.Reader]; 

PictureReal is not implemented. 

55.2.3 Comparison 

Comparison: TYPE = {less, equal, greater}; 

Compare: procedure [a, b: Number] returns [Comparison]; 

Less, LessEq, Equal, GreaterEq, Greater, NotEq: procedure [ 
a, b: Number] returns [boolean]; 

Any of the compare operations may raise Error[notANumber]. 

55.2.4 Operations 

Add, Subtract, Multiply, Divide, Remainder: procedure [ 
a, b: Number]RETURNS [Number]; 

Add, Multiply, Divide and Remainder may raise Error[notANumber] and Error[overflowr] 
Divide may also raise Error[divideByZero]. 

Exp: procedure [Number] returns [Number]; 

Exp computes the results by continued fractions. Exp may raise Error[underflow], 
Error[notANumber] and Error[overflow]. 
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Log: PROCEDURE [base, arg: Number] returns [Number] ; 

Log computes the logarithm to the base base of arg by Ln(arg)/Ln(base). Log may raise 
Error[overflow], Error[invallclOperation], and Error[notANumber]. 

Ln: PROCEDURE [Number] returns [Number]; 

Ln may raise Error[notANumber] , Error[overflow] , and Error[lnvalidOperation]. 
Power: procedure [base, exponent: Number] returns [Number]; 

Power calculates base to the exponent power by e(exponent*Ln(base)). Power may raise 
ErrorlnotANumber] and Error[overflow]. 

Root: procedure [index, arg: Number] returns [Number];- 

Root calculates the index root of arg by e(Ln(arg)/index). Root may raise Error[overflow], 
Error[notANumber], and Error[underflow]. 

SqRt: PROCEDURE [Number] returns [Number]; 

SqRt calculates the square root of the input value by Newton's iteration. SqRt may raise 
Error[notANumber] and Error[invaiidOperation]. 

Abs, Negative, Double, Half: procedure [Number] returns [Number]; 

Abs, Negative, Double and Half may raise Error[notANumber] Double may also raise 
Error(overflow] 

Cos: procedure [radians: Number] returns [cos: Number]; 
Sin: procedure [radians: Number] returns [sin: Number]; 
Tan: procedure [radians: Number] returns [tan: Number]; 

Sin, Cos and Tan may raise Error[notANumber] and Error[invalidOperation]. Tan may 
also raise Error[overflow]. Computes the trigonometric function by polynomial. 

ArcCos procedure [x: Number] returns [radians: Number]; 
ArcSin procedure [x: Number] returns [radians: Number]; 
ArcTan procedure [x: Number] returns [radians: Number]; 

Transcendental functions have an accuracy of about I X 10_ ^\ ArcCos, ArcSin and ArcTan 
may raise Error[notANumber]. ArcSin may also raise Error[invalidOperation]. 

55.2.5 Special Numbers 

A client can create special numbers that will cause the Error[notANumber] to be raised if 
used in any arithmetic operation. 

Speciailndex: type = natural; 

MakeSpecial: procedure [index: Speciailndex] returns [Number]; 
IsSpecial: procedure [Number] returns [yes: boolean, index: Speciailndex]; 
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55.2.6 Errors 

Error: error [code: ErrorCode]; 

ErrorCode: type = {bug, divideByZero, invaiidOperation, notANumber, overflow, 
underflow, unimplemented}; 

notANumber The term not ANumber means the number passed in is a 

special number. 

55.2.7 Special Constants 

zero: Number * loophole[ Bits(0, 0, 0] ]; 

Pi: procedure returns [Number]; 
E: procedure returns [Number]; 

55.3 Usage/Examples 

55.3.1 Special Numbers 

—Make the special number 

special :xLReai. Number <- xLReai.MakeSpecial[1]; 

"do some computations with Numbers 

—If a problem occurs during computation, assign 
n<— special 

[] <-XLReal.Ln[n]; 

—Ifn = special this call to XLReal. Ln will raise Error[notANumber] 

55.3.1 Times of Common Operations 

For the four arithmetic operations, typical timings (in microseconds) compared with the 
current Common Software 32-bit IEEE floating-point package (with no microcode assist) 
are: 





XLReal 


REAL 


Add or Subtract 


500 


800 


Multiply 


800 


1000 


Divide 


1500 


1900 
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55.4 Index of Interface Items 



Item 


Page 


Item 


Page 


Abs:PROCEDURE 


3 


IntegerPart: PROCEDURE 


2 


accu racy : constant 


1,4 


IsSpeciahPROCEDURE 


3 


Add .'PROCEDURE 


2 


Less: PROCEDURE 


2 


ArcCos: PROCEDURE 


3 


LessEq: PROCEDURE 


2 


ArcSin .'PROCEDURE 


3 


Ln: PROCEDURE 


3 


ArcTan:PROCEDURE 


3 


Log: PROCEDURE 


2 


Bits: TYPE 


1 


MakeSpecial :procedure 


3 


Compare:PROCEDURE 


2 


Multiply:PROCEDURE 


2 


Comparison :type 


2 


Negative: procedure 


3 


Cos '.PROCEDURE 


3 


NOtEq: PROCEDURE 


2 


Digit: type 


1 


Number: type 


1 


Digits:TYPE 


1 


NumberToPair:PROCEDURE 


1 


Divide:PROCEDURE 


2 


PairToNumber:PROCEDURE 


2 


DOubie:PROCEDURE 


3 


Pi: PROCEDURE 


4 


E: PROCEDURE 


4 


PictureReal :procedure 


2 


Equal :procedure 


2 


Power:PROCEDURE 


3 


Error: ERROR 


4 


ReaderToNumber:PROCEDURE 


1 


ErrorCode:TYPE 


4 


ReadNumber:pROCEDURE 


1 


Exp:PROCEDURE 


2 


Remainder: procedure 


2 


Fix:PROCEDURE 


2 


Root: PROCEDURE 


3 


Float:PROCEDURE 


2 


Sin:PROCEDURE 


3 


FormatReal: PROCEDURE 


2 


Speciallndex: type 


3 


FractionPart:PROCEDURE 


2 


SqRt:PROCEDURE 


3 


Greater: PROCEDURE 


2 


Subtract: PROCEDURE 


2 


GreaterEq:PROCEDURE 


2 


Tan: PROCEDURE 


3 


Half: PROCEDURE 


3 


ValidExponent:TYPE 


1 






zero:coNSTANT 


4 
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56.1 Overview 



The XMessage interface supports the multinational requirements of systems that require 
that the text to be displayed to the user be separable from the code and algorithms that 
utilize it. This allows messages to be defined by workstation applications and the 
international representations of the text to be supplied by developers and translators. The 
XMessage interface defines the message transfer mechanism necessary for applications to 
define application-specific messages, register them with the system, and access them. 

The XMessage interface is just part of the whole message machinery that provides 
multinational text. Applications must be written to rely on messages for their text. There 
is a tool that translates messages and produces a file containing the translated version of 
the messages. 



56.1.1 Message Usage 

Applications define collection of messages and refer to them using a Handle. Each 
message is represented by a unique key relative to that handle. To get the text of a 
message, the client calls Get or GetList. During development of applications, message 
handles are obtained by calling AiiocateMessages and RegisterMessages. When the 
development is completed and a message file is generated, message handles are obtained 
by calling MessagesFromFile or MessagesFromReference. 

Applications should be broken into three parts: the main code of the application that uses 
the messages, the code that defines and initializes the messages, and the code that gets 
message handles from the message file. 



56.1.2 Message Composition and Templates 

Frequently, text presented to the user should include items like names and sizes of objects, 
dates, etc. When defining such messages, it is best to define a single message template 
that allows certain fields to be filled in with this information. The piecemeal approach to 
constructing a understandable sentence normally will not work when the message is 
translated to a different language. 
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Templates are messages that will have additional text merged into them. The fields in 
templates are defined by numbers enclosed in angle brackets if the template contains 
multiple fields, or simply angle brackets, if there is only one field. 

56.2 Interface Items 

36.2.1 Handles 

Handle: TYPE = long pointer to Object; 
Object: type; 

A Handle represents a collection of messages. It is normally associated with a particular 
application. It is obtained from the AllocateMessages operation and is a parameter of 
most operations. 

56.2.2 Getting Messages 

Get: PROCEDURE [h: Handle, msgKey: MsgKey] returns [msg: xstring.ReaderBody]; 

Get returns the message corresponding to the given message key within the group of 
messages specified by h. 

GetList: procedure [h: Handle, msgKeys: MsgKeyList, msgs: StringArray]; 
MsgKeyList: type = long descriptor for array of MsgKey; 
StringArray: type = long descriptor for array of xstring.ReaderBody; 

GetList fills the array of reader bodies with the bodies of the messages whose keys are in 
the message key list. This procedure is equivalent to: 

FORi IN [0.. msgKeys. length) do msgs[i] <-Get[msgKeys[i]]; endloop. 
This procedure will raise Error[invalidMsgKeyListl if msgKeys is nil, 
Error[invalidStringArray] if msgs is nil and Error[arrayMismatch] if the lengths of the two 
descriptors are not equal. 

56.2.3 Composing Messages 

ComposeToFormatHandle: procedure [ 

source: xstring.Reader, destination: xFormat.Handle, args: StringArray]; 

Compose: procedure [ 

source: xstring.Reader, destination: xstring.Writer, args: StringArray]; 

ComposeToFormatHandle and Compose compose a message by replacing the fields in 
source with the text in args. ComposeToFormatHandle uses an XFormat.Handle as the 
destination of the message, while Compose uses an xstring.Writer. A field is specified by a 
number enclosed in angle brackets. These operations may raise Error(invalidString] if 
source is empty and Error[notEnoughArguments] if args is nil. In order to maintain 
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backward compatibility with existing messages, the string array is one origin; i.e., the 
%pi»^ field < 1 > will access args[0]; 

ComposeOneToFormatHandle: procedure [ 

source: xstring.Reader, destination: XFormat.Handie, arg: xstring.Reader]; 

ComposeOne: procedure [ 

source: xstrlng Reader, destination: xstring.Writer, arg: xstring.Reader]; 

ComposeOneToFormatHandle and ComposeOne compose a message by replacing the 
single field in source with arg. ComposeOneToFormatHandle uses an XFormat.Handie as 
the destination of the message, while ComposeOne uses an xstring.Writer. The single field 
is specified by empty angle brackets, < >. These operations may raise Error[invalidString] 
if source is empty and ErrorfnotEnoughArguments] if arg is nil. 

Decompose: procedure [source: xstring.Reader] returns [args: StringArrayj; 

Decompose currently does nothing. 

56.2.4 Defining Messages 

Messages are defined by constructing an array of message entries and registering them 
with the system. 

Messages: type 3 LONG DESCRIPTOR for array OF MsgEntry; 

MsgEntry: TYPE a record [ 
msgKey: MsgKey, 
msg: xstring.ReaderBody, 
transiationNote: long string <- nil, 
translatable: boolean*- true. 
type: MsgType «- userMsg, 
id: MsgID]; 

MsgKey: type = cardinal,- 

MsgType: type = {userMsg, template, argList, menultem, pSheetltem, commandltem, 
errorMsg, infoMsg, promptltem, windowMenuCommand, others}; 

MsgID: type = cardinal; 

Messages describes a group of message entries and is a parameter to RegisterMessages. A 
MsgEntry contains information about each message. The msgKey field is the Handle- 
relative key of the message. The msg field contains the text of the message itself, while all 
other fields are to help in the translation process. The tranlationNote field provides notes 
to the translator. The translatable boolean indicates whether the message should be 
translated. The MsgType enumerated provides a hint how the message will be used. The 
MsgID is a unique identifier for the message. For a given group of messages, each message 
should have a unique value for its MsgID. This id allows the translators to determine 
when a new message has been added or an old message deleted. 
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AllocateMessages: procedure [ 

appiicationName: LONG STRING, maxMsglndex: CARDINAL, I 
dientData: ClientOata, proc: DestroyMsgsProc] 
RETURNS [h: Handle]; 

ClientData: type = long pointer; 

DestroyMsgsProc: type = procedure [dientData: ClientData]; 

AllocateMessages allows a client to define a domain of messages for subsequent registry 
and access. All access to messages will be relative to the returned handle. The 
appiicationName parameter names the message domain to the message implementation. 
maxMsglndex defines the maximum number of messages that will be registered for this 
domain. The ClientData and DestroyMsgsProc parameters are provided to notify the client 
when the DestroyMessages operation is invoked. 

RegisterMessages: procedure [ 

h: Handle, messages: Messages, stringBodiesAreReal: boolean]; 

RegisterMessages allows a client to initialize a domain of messages. It uses the 
StringBodiesAreReal boolean to decide whether to copy the byte sequences of the 
messages. If StringBodiesAreReal is false, it copies the reader body and bytes of the 
messages field in each entry of messages If it is true, RegisterMessages copies the reader 
body of the entry and relies on the bytes to not be deallocated until after a call to 
DestroyMessages ^(iPfc. 

! 

56.2.6 Obtaining Messages from a File 

MessagesFromFile: procedure [ 

fileName: long string, dientData: ClientData, proc: DestroyMsgsProc] 
RETURNS [msgDomains: MsgDomains]; 

MessagesFromReference: procedure [ 

file: NSFiie.Reference, dientData: ClientData, proc: DestroyMsgsProc] 
returns [msgDomains: MsgDomains]; 

MsgDomains: type = longdescriptorfor array of MsgDomain; 

MsgDomain: type = record [ 

appiicationName: xstring.ReaderBody, 
handle: Handle]; 

MessagesFromFile and MessagesFromReference return a sequence of message domains, 
which are name, message handle pairs. MessagesFromFile gets the messages from the file 
named fileName in the system folder, while MessagesFromReference gets the messages 
from the file whose reference is file. Storage for msgDomains must by freed by calling 
FreeMsgDomainStorage. The ClientData and DestroyMsgsProc parameters are provided 
to notify the application when the DestroyMessages operation is invoked. 
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FreeMsgDomainsStorage: procedure [msgDomains: MsgDomains]; 

56.2.7 Destroying Message Handles 

Destroy Messages: procedure [h: Handie]; 

DestroyMessages invokes the DestroyMsgsProc associated with the handle and then frees 
any resources that are currently associated with h. The handle should no longer be used. 



56.2.6 Error 

Error: error [type: ErrorType]; 

ErrorType: type = { 

arrayMismatch, invalidArglndex, invalidMsgKey, invalidMsgKeyList, 
invaiidStringArray, invalidString, notEnoughArguments}; 

56.3 Usage/Examples 

56.3.1 Structuring Applications to Use Messages 

Applications that use messages have at least two parts. The first part is the code that 
implements the functionality of the application. It is produced by programming tools such 
as the compiler and binder with Mesa source programs as input. The second part consists 
of the messages that provide text to the user. The application defines its messages and 
provides initial information to the translators of the messages. 

A serious operational consideration of a workable message facility is that of 
communicating messages (to be translated) in a precise type-safe manner. A consistent 
key/message correspondence with the original versions must be verifiable throughout the 
translation process. 

The cleanest and safest possible interface between application developers (message 
definers) and translators is the delivery of a bed that contains all the messages used by the 
application as well as a well-defined mechanism for communicating them to some client. 
The RegisterMessages procedure provides the mechanism; all that is needed is to avoid 
other distractions (like importing or exporting of application private facilities). To that 
end, the following conventions are proposed for modules/configurations that define and 
register messages: 

1. Message definition code must be isolated into modules whose sole function is to define 
and register the message text for the application. 

2 The allocation of the Handle and registration of all messages must be accomplished 
via the modules' configuration's START code. 

3 If multiple modules are required to define the application messages, provide a 
configuration that will start all modules in the the correct order and provide the 
correct imports and exports 
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4 XMessage definition modules/configurations must not depend upon application- 
specific facilities. Specifically, this means that the imports list of any message-defining 
module should be restricted to procedures defined in the XMessage interface (such as 
RegisterMessages, AllocateMessages, etc.). 

As a consequence of conventions 2 and 4 above, applications must provide a mechanism for 
communicating the Handle between suppliers of messages (callers of ResisterMessages) 
and users of messages (callers of GetMsg and and so forth) . A simple solution is to have 
the message-definition module export a procedure that returns the handle. 

56.3.2 Example of Message Usage 

The following message example has three segments. The first is an interface that defines 
the messages for the example. The second is the module that provides the raw material for 
the messages. This module is used to supply the message text while running the 
application while it is being developed and is used to supply the raw data to the message 
translators. The third part is the module that uses the messages. 

-- ExampleMessage.mesa 

DIRECTORY 

XMessage using [Handle]; 

ExampleMessage: definitions = begin 

Keys: type = machine dependent { 

delete(O), confirmDelete(l), deleteDone(3)...}; 

GetHandle: procedure RETURNs[h: xMessage.Handle]; 

END. -- of ExampleMessage: 



— ExampleMessagelmpl.mesa 

DIRECTORY ... 

ExampleMessagelmpI: program 
IMPORTS ... 

EXPORTS ExampleMessage - begin 
h: XMessage.Handle; 

GetHandle: public procedure returns [xMessage.Handle] s {returnEH]}; 
DeieteMessages: XMessage. DestroyMsgsProc = {}; 

Init: PROCEDURE = { 

msgArray: array Keys OF XMessage. MsgEntry <— [ 
delete: [ 

msgKey: Keys.delete.ORD, 
msg : xstring. FromSTRI NG[ " Delete " Ll , 
translationNote: "Delete command name"L, 
translatable: true. 
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type: menultem, 
id: 0], 
confirmDelete: [ 

msgKey: Keys.confirmDelete.ORD, 

msg: xstring.FromSTRING["Are you sure you want to delete that item"L], 
translatable: true, 
type: userMsg, 
ld:lL 
deleteDone: [ 

msgKey: Keys.deieteDone.ORD, 

msg: xstring.FromSTRING("The item <1 > has been deleted"L], 
translatable: true, 
type: template, 
id:31]; 

h XMessage.AllocateMessages[ 

"Example"L, Keys. last.ord.succ, nil, Deleteiyiessages]; 
XMessage.RegisterMessages[h,LOOPHOLE[LONG[DESCRiPTOR[msgArray]l], false]}; 

Initn; 

END. — of ExampleMessagelmpI 
- Examplelmpl.mesa 

DIRECTORY ... 

^p*'^ ExamplelmpI: PROGRAM 

IMPORTS XMessage, ExampleMessage s begin 

h: XMessage.Handle s ExampleMessage. GetHandie[] 

DeleteOne: procedure [ . . . ] = { 

r: xstring. Reader = XMessage.Get[h, ExampleMessage. Keys.confirmDelete.ORD]; 

'};' 

}. " of ExamplelmpI 
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56.4 Interface Item Index 
Item 

AllocateMessages: procedure 

ClientDatarTYPE 

Compose: procedure 

ComposeOne: procedure 

ComposeOneToFormatHandleiPROCEDURE 

ComposeToFormatHandle: procedure 

Decompose: procedure 

Destroy Messages : procedure 

Destroy MsgsProc: type 

Error: error 

ErrorType: TYPE 

FreeMsgDomainsStorage: procedure 

Get: procedure 

GetList: procedure 

Handle: type 

Messages: TYPE 

MessagesFromFile: procedure 

MessagesFromReference: procedure 

MsgDomains:TYPE 

MsgEntry: type 

MsglD: type 

MsgKey: type 

MsgKeyList: type 

Msg Type: type 

Object: type 

RegisterMessages: procedure 
String Array: type 



X String 



57.1 Overview 

The XString interface is part of a string package that supports the Xerox Character 
Standard. It provides the basic data structures for representing encoded sequences of 
characters and some operations on these data structures. 

57.1.1 Character Standard 

The Xerox Character Code Standard defines a large number of characters, encompassing 
not only familiar ASCII characters but Japanese and Chinese Kanji characters and other 
characters to provide a comprehensive character set able to handle international 
information-processing requirements. Because of the large number of characters, the data 
structures in XString are more complicated than a long string's simple array of ASCII 
characters, but the operations provided are more comprehensive. 

Characters are 16-bit quantities that are composed of two 8-bit quantities: their character 
set and character code within a character set. The Character Standard defines how 
characters may be encoded, either as runs of 8-bit character codes of the character set or as 
16-bit characters where the character set and character code are in consecutive bytes. See 
the XChar chapter for information and operations on characters. 



57.1.2 Data Structures 

Three main data structures are defined by XString; Context, ReaderBody and WriterBody. 
Contexts provide information for determining how characters are encoded. Reader bodies 
and readers describe a sequence of readonly characters. Writer bodies and writers describe 
a sequence of writeable characters. 

A Context contains information about how characters are encoded in the byte sequence. 
The sufflxSize field describes whether the first byte is encoded as an 8-bit character or a 
16-bit character, the prefix field contains the character set of the first character if the 
encoding is 8-bit characters, and the homogeneous field is true only if there are no 
character set shifts in the sequence of characters. 

A ReaderBody describes some readonly characters that are stored as a sequence of bytes. 
The reader body contains a pointer to the allocation unit containing the bytes, bytes, the 
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offset from the pointer to the first byte, off set, the offset from the pointer of the byte after 
the last byte in the byte sequence, limit, and the context information describing how the 
first character is encoded, context. Most clients should not have to access fields of a reader 
body. Many operations take a Reader, a pointer to a reader body, as a parameter to reduce 
the number of words of parameters. 

A WriterBody describes some characters that may be edited. In addition to containing all 
the information in a reader body, it also contains an offset from the pointer to the first 
character not in the allocation unit, maxLimit, the context that describes how the last 
character is encoded, endContext, and the zone that contains the allocation unit, zone. 
Writer bodies are typically passed by reference. 

The designers of XString felt there is a fundamental difference between a string that will 
only be read and one that will be constructed. They felt that the major usage of strings was 
to describe and examine existing strings, not construct new ones. This difference is 
reflected in the two types, readers and writers. 



57.1.3 Operations 



There are a wide range of operations on both readers and writers. Some operations that 
return simple information about readers, such as ByteLength and Empty. Others access 
characters in a reader, such as First, NthCharacter, and Lop. The operation, 
ReaderFromWriter can be used to convert a writer to a reader. 

There are operations that create reader bodies from other data structures, such as 
FromSTRING. Similarily, there are operations that create writer bodies from other 
structures, such as WriterBodyFromSTRING. 

Routines allocate and deallocate byte sequences of both readers and writers 
CopyToNewReaderBody makes a copy of the characters of a reader NewWriterBody will, 
create an empty writer body that can hold a given number of bytes 
CopyToNewWriterBody is similar to NewWriterBody but initializes the writer with a 
given reader. 

Other operations compare the characters in readers: Equal checks for equality and 
Compare does a multinational lexical comparison. There are operations for scanning 
readers for specific characters. The operation ReaderToNumber converts a reader to a 
numeric value. There are Courier description routines for both readers and reader bodies. 
There is also support for backward-accessing characters in a reader. 

Routines are provided for appending to writers and editing writers. AppendReader 
appends the characters of a reader to a writer. ReplacePiece provides a general editing 
operation for writers. Only the basic appending primitives are provided in XString. The 
XFormat interface can be used to append converted values, such as numbers, to writers. 



57.2 Interface Items 



57.2.1 Contexts ^ 

I 
i 

Context: TYPE ■ machine dependent record ( 
suffixSize(0:0..6): [1..21, 
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homogeneous(0:7..7): boolean, 
prefix(0:8..15): Byte]; 

A Context contains information about how characters are encoded in the byte sequence. 
The suffixSize field describes whether the first byte is encoded as an 8-bit character or a 
16-bit character, the prefix field contains the character set of the first character if the 
encoding is 8-bit characters, and the homogeneous field is true only if there are no 
character set shifts in the sequence of characters. 

The Character Set Standard describes how characters may be encoded as a sequence of 
bytes. They call the 8-bit character encoding stringletS and call the 16-bit character 
encoding stringletl6. In 8-bit character encoding, consecutive bytes contain character 
codes of characters in the same character set. In 16-bit character encoding, the character 
set and character code are contained in consecutive bytes. The suffixSize field describes 
how the characters are encoded; it is 1 for 8-bit character encoding and 2 for 16-bit 
. - character encoding. 

The prefix field contains the character set of the first character if it is an 8-bit encoded 
character. Subsequent characters in the string use this same prefix unless a character set 
or encoding transition is encountered. It is not used for 16-bit encoded characters. 

The homogeneous field is an accelerator. If it is true, some operations may be faster. It is 
important to set it TRUE only if the byte sequence contains no character set shifts. It is 
always safe to set it to false. 

emptyContext: Context ■ [suffixSize: 1, homogeneous: true, prefix: 0]; 

vaniilaContext: Context « [suffixSize: 1, homogeneous: false, prefix: 0]; 

unl<nownContext: Context = [suffixSize: 1, homogeneous: false, prefix: 377B]; 

emptyContext, vaniilaContext, and unknownContext are three Context constants. An 
empty writer should have emptyContext as its context and endContext. vaniilaContext is 
the default context. unknownContext signifies that the context is unknown. It is 
generally used only for an end context, a context that describes the last character of a 
sequence. 

57.2.2 Readers and Reader Bodies 

Reader: TYPE « long pointer to ReaderBody; 

ReaderBody: type a private machine dependent record [ 
context(O): Context, 
limit(l): cardinal, 
offset(2): cardinal, 
bytes(3): ReadOnlyBytes]; 

ReadOnlyBytes: type = long pointer to readonly ByteSequence; 

ByteSequence: TYPE « record! 

PACKED SEQUENCE COMPUTED CARDINAL OF Byte]; 
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Byte: type = Environment.Byte; 

A ReaderBody describes some readonly characters that are stored as a sequence of bytes. 
The reader body contains a pointer to the allocation unit containing the bytes, bytes, the 
offset from the pointer to the first byte, offset, the offset from the pointer of the byte after 
the last byte in the byte sequence, limit, and the context information describing how the 
first character is encoded, context. Most clients should not have to access fields of a reader 
body. Reader bodies can be thought of as fat pointers. Many operations take a Reader, a 
pointer to a reader body, as a parameter to reduce the number of words of parameters. 

A ReaderBody is like a substring descriptor. The offset and limit fields can be changed to 
describe a subsequence of bytes. Routines such as Lop and ScanForCharacter take 
advantage of this substring-like behavior. 

nullReaderBody: ReaderBody s [ 

limit: 0, offset: 0, bytes: nil, context: vanillaContext]; 

nullReaderBody defines a null value for a reader body. To test for an empty reader body, it 
should not be compared to nullReaderBody. The operation Empty should be used instead. 



57.2.3 Writers and WriterBodies 



Writer: TYPE » longpointerto WriterBody; 



WriterBody: TYPE = private machine dependent record [ 
context(O): Context, 
limit(l): cardinal. 
offset(2): cardinal, 
bytes(3): Bytes, 
maxLimit(5): cardinal, 
endContext(6): Context, 
zone(7): uncounted zone]; 



Bytes: TYPE a long pointer to ByteSequence; 



Writers describe a sequence of bytes that may be changed. Writers are bit-wise compatible 
with a reader and contain additional information for storage management and appending 
characters. The maxLimit field describes the limits of the allocation unit, the zone field is 
the zone used for allocating and freeing the bytes, and the endContext field is an 
accelerator for operations that append characters. 

By including a zone in the writer body, operations that add characters to the writer are 
able to allocate a larger byte sequence, copy the old bytes, and update the byte pointer in 
the writer body without invalidating the writer variable that the caller owns. 

null WriterBody: WriterBody = ( 

limit: 0, offset: 0, bytes: nil, context: vanillaContext, maxLimit: 0, 
endContext: vanillaContext, zone: nil]; 

nullWriterBody defines a null value for a writer body. 
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57.2.4 Simple Reader Operations 

ByteLength: procedure [r: Reader] returns [cardinal] = inline 
ByteLength returns the number of bytes in r. If r is nil, it returns zero. 
CharacterLength: procedure [r: Reader] returns [cardinal]; 

CharacterLength returns tlie number of logical characters in r. If r is nil it returns zero. If r 
is a valid reader, then ByteLength[r] a 0 iff CharacterLength[r] = 0. If r contains an 
invalid encoding, CharacterLength will raise the error InvaiidEncoding. 

Dereference: procedure [r: Reader] returns [rb: ReaderBody]; 

Dereference returns nullReaderBody if r is nil and r f otherwise. 

Empty: procedure [r: Reader] returns [boolean] a inline 

Empty returns true if r is nil or ByteLength[r] = 0. 

Readerlnfo: procedure [r: Reader] returns [context: Context, startsWith377B: boolean] ; 

Readerlnfo returns the context of the reader and whether the first byte of the reader is 
377B, the character set shift code. 

57.2.5 Accessing Characters 

Because of the large number of characters in the character set standard and the way they 
are encoded, it is normally not possible to access characters of a reader by indexing. 
Instead, a number of operations are provided to access characters. 

First: procedure [r: Reader] returns [c: Character]; 

First returns the first logical character. It is equivalent to NthCharacter[s, 0] but is usually 
more efficient. If Empty [r] then XChar.not is returned. It may raise the InvaiidEncoding 
error. 

NthCharacter: procedure [r: Reader, n: cardinal] returns [c: Character]; 

NthCharacter returns the nth logical character. First should be used if n = 0. If 
CharacterLength[r] < » n then XChar.not is returned. It may raise the InvaiidEncoding 

error. 

Lop: PROCEDURE [r: Reader] returns [c: Character]; 

Lop removes the first character from the front of a reader and returns it. If r is empty it 
returns XChar.not. If r contains one logical character, Lop sets r to be empty and returns 
the first logical character. Otherwise, Lop modifies r to point to the second logical 
character and returns the first. It may raise the InvaiidEncoding error. 
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Map: PROCEDURE [r: Reader, proc: MapCharProc] returns [c: Character]; 
MapCharProc: type = proc [c: Character] returns [stop: boolean]; 

Map enumerates the reader, calling proc once for each character in r. If proc returns true 
it returns that character; otherwise it returns XChar.not. It is equivalent to: 

FOR i: cardinal IN [O..CharacterLength[r]) oo 

IF proc[c <- NthCharacter[r, i]] then return[c]; endloop 
RETURN[XChar.notl ; 

Map may raise the InvalidEncoding error. 



57.2.6 Errors 



Error: error [code: ErrorCode] ; 



ErrorCode: type = { 

invalidOperation, multipleCharSets, tooManyBytes, invalidParameter}; 

invaiidOperation an invalid operation has been attempted. 

multipleCharSets InitBreakTable has been called with a reader that contains multiple 
character sets. 



tooManySytes 



a LONG string has been passed to FromSTRING or 
WriterBodyFromSTRING and the string contains too many bytes. 
These operations use the string as the byte pointer so the offset is 
non-zero, reducing the number of bytes it may hold. This is also 
raised by CopyReader for a similar reason. 



invalidParameter The term invalidParameter means an operation has been invoked 
with an invalid parameter. 



InvalidEncoding: error [invalidReader: Reader, firstBadByteOffset: cardinal] ; 

The error InvalidEncoding is raised by operations when they detect a sequence of bytes 
that is not a valid character encoding. While two character set shifts with no intervening 
character is an invalid encoding according to the character standard, only Validate Reader 
will raise InvalidEncoding if it detects that case. The other operations will ignore the first 
character set shift. Invalid encodings include ending with a character set shift or partial 
character set shift and having a non-zero byte following two 377B bytes. 



57.2.7 Conversion to Readers 

ReaderFromWriter: procedure [w: Writer] returns [Reader] s inline ... ; 

ReaderFromWriter provides a conversion from the type Writer to the type Reader. This 
operation takes advantage of the fact that the first part of writer bodies are bit-wise 
compatible with reader bodies, and hence this operation simply loopholes the writer into 
the reader. 
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FromBlock: procedure [ 

block: Environment.Block, context: Context ^ vanillaContext] returns [ReaderBody]; 

FromBlock returns a reader body that describes the block. 

FromChar: procedure [char: long pointer to Character] returns [ReaderBody]; 

FromChar returns a reader body that describes the character. The pointer to the character 
must remain valid for the lifetime of the reader body. 

FronnNSString: procedure [s: Nsstring.String, homogeneous: boolean false] 
returns [ReaderBody]; 

FromNSString returns a reader body that describes the characters in the NSString. The 
context of the reader body will be [suffixSize: 1, homogeneous: homogeneous, prefix: 0]. 

FromSTRING: procedure [s: long string, homogeneous: boolean <- false] 
returns [ReaderBody]; 

FromSTRING returns a reader body that describes the characters in the long string. The 
context of the reader body will be [suffixSize: 1» homogeneous: homogeneous, prefix: 0]. 
This operation may raise Error[tooMany Bytes] if the string contains more than 
CARDiNAL.LAST-StringBody.SiZE * Environment. bytesPerWord bytes. 

57.2.8 Reader Allocation 

CopyReader: procedure [r: Reader, z: uncounted zone] returns [new: Reader]; 

CopyReader makes a copy of the reader body and characters of r, allocating from z as a 
single allocation unit, the byte sequence for the characters, and the reader body. Note that 
this operation returns a reader while all other operations in this interface that create a 
reader or reader body return the reader body. The reason is to avoid a double allocation 
problem in which the byte sequence and reader body are allocated from two separate 
nodes. FreeReaderBytes can be used to free the new reader and the associated bytes. Note: 
This operation may raise Error[tooManyBytes] if the reader contains more than 
CARDINAL.LAST • ReaderBody. SIZE * Envlronment.bytesPerWord bytes. Errors in allocating 
from the zone are allowed to propagate. 

CopyToNewReaderBody: procedure [r: Reader, z: uncounted zone] returns [ReaderBody]; 

CopyToNewReaderBody allocates a copy of the bytes of r using z and returns a reader 
body describing them. If r is nil it returns nullReaderBody. Errors in allocating from the 
zone are allowed to propagate. 

FreeReaderBytes: procedure [r: Reader, z: uncounted zone]; 

FreeReaderBytes may be used to free the storage allocated by CopyReader and 
CopyToNewReaderBody. If r is non-NiL and z is non-NiL, it frees r.bytes to the zone. When 
the reader has been obtained from CopyReader, FreeReaderBytes will free the single 
allocation unit that contains both the reader body and byte sequence. When the reader has 
been obtained from CopyToNewReaderBody, FreeReaderBytes will free the allocation 
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unit that contains the byte sequence but will not free the reader body. Errors in freeing to 
the zone are allowed to propagate. 

57.2.9 Simple Writer Operations 

ClearWriter: procedure [w: Writer]; 

ClearWriter makes w empty. It is analogous to the long string statement s. length <— 0. 

Writerlnfo: procedure [w: Writer] 

RETURNS [unused: cardinal, endContext: Context, zone: uncounted zone]; 

Writerlnfo returns the number of allocated but unused bytes of a writer as well as its 
endContext and its zone. 

57.2.10 Conversion to Writers 

WriterBodyFromBlock: procedure [block: Environment.Block, inllse: cardinal <-0] 
RETURNS [WriterBody]; 

WriterBodyFromBlock returns a writer body that describes the block. The writer body's 
offset and maxLimit fields are set from the block's startlndexandstoplndexPlusOne fields, 
respectively. The inUse parameter is used to set the limit field of the writer body. If the 
block's pointer is nil or inUse is larger than the number of bytes in the block, 
Error[invalidParameter] is raised. 

WriterBodyFromNSString: procedure [ 

s: NSString.String, homogeneous: boolean <- false] returns [WriterBody]; 

WriterBodyFromNSString returns a writer body that describes the characters in the 
NSString. Its context is [suffixSize: 1, homogeneous: homogeneous, prefix: 0]. 

WriterBodyFromSTRING: procedure [ 

s: LONG string, homogeneous: boolean false] returns [WriterBody]; 

WriterBodyFromSTRING returns a writer body that describes the characters in the long 
string. Its context is [suffixSize: 1, homogeneous: homogeneous, prefix: 0]. This 
operation may raise Error[tooManyBytes] if the string contains more than cardinal.last ■• 
StringBody.sizE * Environment.bytesPerWord bytes. 

57.2.11 Writer Allocation 

NewWriterBody: procedure [maxLength: cardinal, z: uncounted zone] 
RETURNS [WriterBody]; 

NewWriterBody allocates a byte sequence that has room for maxLength bytes using z and 
returns an empty writer body that contains the bytes. Errors in allocating 
ByteSequence[maxLength] from the zone are allowed to propagate. 
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CopyToNewWriterBody: procedure [ 

r: Reader, z: uncounted zone, endContext: Context unknownContext, 
extra: cardinal «- 01 returns [w: WriterBodyl; 

CopyToNewWriterBody allocates a byte sequence that has room for ByteLength[r] + extra 

bytes using z, copies the bytes of r into the newly allocated byte sequence, and returns an 
writer body that contains the bytes. The end context of the writer body is endContext. 
Errors in allocating from the zone are allowed to propagate. 

ExpandWriter: procedure [w: Writer, extra: cardinal]; 

ExpandWriter assures that at least extra bytes are available in the writer's bytes. If 
w.zone is nil, then Error[invaiidOperation] is raised. Errors in allocating a new byte 
sequence if required are allowed to propagate. 

FreeWriterBytes: procedure [w: Writer]; 

FreeWriterBytes may be used to free the byte sequence of a writer as long as it was 
allocated from the writer's zone. It may be used to free the byte sequence of writers created 
by CopyToNewWriterBody and NewWriterBody. If w is non-NiL and w.zone is non-NiL, it 
frees w.bytes to the zone. Note that it does not free the writer body. Errors in freeing to the 
writer's zone are allowed to propagate. 



57.2.12 Comparison of Readers 

Equal: procedure [r1, r2: Reader] returns [boolean]; 

Equal returns true if and only if the number of logical characters is equal and the strings 
match when compared character by character, i.e., effectively CharacterLength[r1] = 
CharacterLength[r2] and NthCharacter[r1, i] a NthCharacterfrZ, i] for i in the range [0.. 
CharacterLength(r1]). It may raise the InvalidEncoding error. 

Equivalent: procedure [r1, r2: Reader] returns [boolean]; 

Equivalent returns true if and only if the number of logical characters is equal and the 
strings match when compared character by character, ignoring case. It is equivalent to: 

IF CharacterLength[r1] # CharacterLength[r2l then returnifalse); 
for i: cardinal IN [O..CharacterLength[r1]) do 

IF Decase[NthCharacter[r1, i]] # Decase(NthCharacter[r2, i]] then returnifalse]; 

ENDLOOP; 

returnitrue). 

Equivalent may raise the InvalidEncoding error. 

SortOrder: type = machine dependent { 

standard(O), spanish(1), swedish(2), danish(3), firstFree{4), null(377B)}; 

SortOrder is a parameter to Compare and CompareStringsAndStems that specifies the 
sort order, danish, Spanish, and Swedish differ from standard only in some characters in 
character set zero. 
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Compare: procedure [ 

r1, r2: Reader, ignoreCase: boolean <-true, sortOrder: SortOrder «- standard] 
RETURNS [Relation]; 

CompareStringsAndStems: procedure [ 

r1, r2: Reader, ignoreCase: boolean ♦-true, sortOrder: SortOrder <- standard] 
RETURNS [relation: Relation, equalStems: boolean]; 

Relation: type = {less, equal, greater}; 

Compare and CompareStringsAndStems compare two readers. They return a relation 
indicating the sorted relationship of their arguments with the case of characters 
optionally ignored during the comparison. In CompareStringsAndStems, equalStems will 
be TRUE if both readers are equal up to the length of the shorter. They may raise the 
InvalidEncoding error. 

57.2.13 Numeric Conversion of Readers 

ReaderToNumber: procedure [ 

r: Reader, radix: cardinal <- 10, unsigned: boolean ^-false] returns [long integer]; 

ReaderToNumber converts the characters in the reader to a number. If radix is other than 
8, 10, or 16, XString.Error(invalidOperation] is raised. The syntax for a number is: 

{•- 1 ' + f {baseNumber} {"b | 'B I'd | 'D | 'h I'H} {scaleFactor} 

where 0 indicates an optional part and "|" indicates a choice, and baseNumber and 
scaleFactor are sequences of digits. The value returned is ± baseNumber * radix ** 
scaleFactor. The radix depends on the contexts of r and radix. If r contains a 'B or 'b, radix 
is 8; if it contains a 'D or 'd, radix is 10, if it contains a 'h or 'H, radix is 16; otherwise it is 
radix. The number scaleFactor is always expressed in radix 10. If r does not have valid 
form, or r does not contain any characters, or radix is 8 and non-octal digits are used, or 
unsigned is true and the reader contains a minus sign, the signal InvalidNumber is raised. 
If it is resumed, the operation returns zero. If unsigned is true and the number would 
overflow 232-1 or unsigned is false and the number is not in the range [-231 . 23 1), the 
signal Overflow is raised. If it is resumed, the operation returns zero. ReaderToNumber 
may raise the InvalidEncoding error. 

InvalidNumber: signal; 

The signal InvalidNumber is raised by the string to number operations when the string is 
the wrong syntax for a number. Resuming this signal results in the operation returning 
zero. 

Overflow: signal; 

The signal Overflow is raised by the string to number operations when the string 
describes a number that is too large. Resuming this signal results in the operation 
returning zero. 
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57.2.14 Character Scanning 

ScanForCharacter: procedure [r: Reader, char: Character, option: BreakCharOption] 
RETURNS [breakChar: Character, front: ReaderBodyl 

BreakCharOption: TYPE = {ignore, appendToFront, leaveOnRest}; 

ScanForCharacter scans the string for the first instance of char. If char is found in r, the 
characters before it will be described by front and the characters after it will be described 
by r. char will be on the end of front, discarded, or left on the front of r | if option is 
appendToFront, ignore, or leaveOnRest, respectively, char will be returned as breakChar. 
If it does not encounter char in r, then front will be equal to r | as it was when the 
procedure was invoked and r| will be updated to be 0 characters long, xchar.not will be 
returned as breakChar. ScanForCharacter may raise the lnvalidEncoding.error. 

Scan: procedure [r: Reader, break: BreakTable, option: BreakCharOption] 
RETURNS [breakChar: Character, front: ReaderBody]; 

BreakTable: TYPE = long pointer to BreakTableObject; 

BreakTableObject: type = record 
otherSets: StopOrNot stop. 
set:Environment.Byte <- 0, 

codes: packed array [0..256) of StopOrNot <r- ALL[not]]; 
StopOrNot: type = {stop, not} not; 

Scan is like ScanForCharacter except that it can scan for any number of character codes in 
a particular character set. The BreakTable defines which character codes of a character set 
are scanned for. Scanning is searching for the first character, c, such that 

(xchar.Set[c] a break.set AND break. codes[xchar.Code[c]] = stop) or 
(xchar.Set[c] # break.set and break.otherSets a stop). 

The disposition of the character that terminates scanning depends on option as in 
ScanForCharacter. If the character terminated scanning because it was in a different 
character set, xchar.not will be returned as breakChar. Scan may raise the 
InvalidEncoding error. 

InitBreakTable: procedure [ 

r: Reader, StopOrNot: StopOrNot, otherSets: StopOrNot] 
RETURNS [break: BreakTableObject]; 

InitBreakTable initializes a BreakTableObject to stop (or not stop) on the characters of r 
depending on StopOrNot. If r has multiple character sets, Error[multipleCharSets] is 
raised. InitBreakTable may raise the InvalidEncoding error. 

57.2.15 Other Reader Operations 

^m0^ ComputeEndContext: procedure [r: Reader] returns [c: Context]; 
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ComputeEndContext returns the context of the last character in r. If CharacterLength[r]! 
= 0 then empty Context is returned. ComputeEndContext may raise the InvalidEncodingi 

error. 

DescribeReader: courier. Description; 

DescribeReader is a Courier description routine. It is provided for clients that need to 
serialize and deserialize readers. 

Oescri beReaderBody : courier. Descri ption ; 

OescribeReaderBody is a Courier description routine. It is provided for clients that need to 
serialize and deserialize readers bodies. 

Run: PROCEDURE [r: Reader] returns [run: ReaderBody]; 

Run is like Lop except that it deals in homogeneous runs of characters instead of single 
characters. It will return a reader body describing the first homogeneous run of r and 
update r to remove the run. If Empty[r] it returns nullReaderBody It may raise the 
InvalidEncoding error. 

VaiidateReader: procedure [r: Reader]; 

VaiidateReader checks the bytes of r to ensure that it is a valid encoding. If it is not a valid 
encoding, the error InvalidEncoding is raised. Possible invalid encodings include ending in 
a character set shift with no character or following two successive 377B bytes by a non- 
zero byte, null run, two character set shifts with no intervening character, is an invalid 
encoding that is checked by VaiidateReader. If the offset is greater than the limit or the 
byte pointer is nil and the offset and limit are not equal, then ErrorfinvalidParameter] is 
raised. 



The operations in this section append to writers. When there is insufficient space in the 
writer to hold the bytes to be appended, the operations attempt to allocate from the 
writer's zone a new byte sequence of sufficient size. If there is insufficient space and the 
writer's zone is nil, the signal Insuff icientRoom is raised. If it is resumed, the operations 
will append as many characters as will fit. Errors resulting from allocating from the zone 
are allowed to propagate. An expanded set of appending operations are available using the 
XFormat interface. 

AppendReader: procedure [ 

to: Writer, from: Reader, fromEndContext: Context <- unknownContext, 
extra: cardinal «- 0]; 

AppendReader appends the reader to the writer. If either the reader or writer is nil, this 
operation simply returns. The end context of the writer is updated to fromEndContext if it 
is not unknownContext and ComputeEndContext[r] otherwise. The signal 
InsufficientRoom may be raised as described above. Jfi^ 

AppendChar: procedure [to: Writer, c: Character, extra: cardinal 0]; 



57.2.16 Appending to Writers 
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AppendChar appends the character to the writer. If the writer is nil, this operation simply 
returns. The signal InsufficientRoom may be raised as described above. If it is resumed, 
nothing is appended. 

AppendStream: procedure [ 

to: Writer, from: stream. Handle, nBytes: cardinal, 
fromContext: Context «- unknownContext, extra: cardinal «-0] 
returns [bytesTransf erred: cardinal]; 

AppendStream appends nBytes from the stream from to the writer. If either the stream or 
writer is nil, this operation simply returns. The end context of the writer is updated to 
fromEndContext if it is not unknownContext and ComputeEndContext[r] otherwise. The 
signal InsufficientRoom may be raised as described above. If it is resumed, as much of the 
reader as will fit in the space available is appended. AppendStream returns the actual 
number of bytes transferred. 

Note: There is currently a bug in the interface such that the fromContext parameter is 
defaulted to vanillaContext instead of unknownContext. 

AppendSTRING: procedure [ 

to: Writer, from: long string, homogeneous: boolean <- false, extra: cardinal <- 0]; 

AppendSTRING appends the string to the writer. If either the string or writer is nil, this 
operation simply returns. The end context of the writer is updated to vanillaContext if 
homogeneous is true, otherwise its value is computed from the parameter from. The 
signal InsufficientRoom may be raised as described above. 

InsufficientRoom: signal [needsMoreRoom: Writer, amountNeeded: cardinal]; 

The signal InsufficientRoom is raised by the append operations when the writer does not 
have enough room to contain the appendee and the writer's zone is nil. Resuming this 
signal will result in as much as possible being appended. 

AppendExtensionlf Needed: procedure [to: Writer, extension: Reader] 
returns [didAppend: boolean]; 

AppendExtensionlfNeeded checks to see if there is a period somewhere in the writer other 
than the last character. If there is, false is returned If not, it appends a period if the writer 
does not already end in one, then appends extension and returns true. AppendChar and 
AppendReader are used to append and they may raise InsufficientRoom. 



57.2.17 Editing Writers 

Piece: procedure [r: Reader, firstChar, nChars: cardinal] 
RETURNS [piece: ReaderBody, endContext: Context]; 

Piece returns a reader body that describes the firstChar through firstChar + nChars logical 
characters of r. piece will describe as many characters of r that are in that range, possibly 
none if CharacterLength[r] is less than or equal to firstChar. The context of the last 
character of piece is also returned. It may raise the InvalidEncoding error. ^ 
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ReplacePiece: procedure [ 

w: Writer, firstChar, nChars: cardinal, r: Reader, 
endContext: Context *- unknownContext]; 

ReplacePiece is an editing operation for \vriters. It replaces nChars of w starting at 
firstChar with the characters of r. nChars may be zero and r may be empty. If the reader is 
not empty, endContext is needed to update the end context of the writer if the piece 
replacement is at the end, or to determine if there needs to be a character set shift between 
the bytes of r and the (firstChar + nChar)th character of w. If endContext is 
unknownContext it will be computed from r. The signal InsufficientRoom may be raised 
as described above if the operation resulted in a net addition of bytes. ReplacePiece may 
raise the InvalidEncoding error. 

57.2.18 Conversion from Readers 

Block: PROCEDURE [r: Reader] returns [block: Environment.Block, context: Context] ; 

Block returns both a block that describes the bytes in r as well as the context of r. This 
operation may be used by clients that need to examine the bytes directly. Note: The bytes 
of the block should not be written. 

NSStringFromReader: procedure [r: Reader, z: uncounted zone] 
RETURNS [ns: NSString.String] ; 

NSStringFromReader creates an NSString.String from a reader. It always copies the bytes of 
the reader into a new allocation unit allocated from the zone. The resulting string should 
be deallocated using operations from the NSString interface. Errors from allocating from 
the zone are allowed to propagate. 

57.2. 19 Reverse Character Operations 

ReverseMap: procedure [r: Reader, proc: MapCharProc] returns [c: Character]; 

ReverseMap is similar to Map, except it enumerates the characters in reverse order. It is 
less efficient than Map because encoding characters makes backward scanning difficult. It 
may raise the InvalidEncoding error, 

ReverseLop: procedure [ 

r: Reader, endContext: long pointer to Context, 
backScan: BackScanClosure <- [nil, nil]] 
RETURNS [c: Character]; 

BackScanClosure: type a record [proc: BackScanProc, env: long pointer]; 

BackScanProc: type = procedure [beforePos: cardinal, env: long pointer] 
returns [pos: cardinal, context: Context]; 

ReverseLop is similar to Lop, except it takes characters off the end of the reader. It is less 
efficient than Lop because encoding characters makes backward scanning difficult. If the 
reader is empty, it returns xchar.not. If endContext | is not unknownContext, then it 
must be correct. It may be changed by a call to ReverseLop. If ReverseLop backs up over a 
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character set shift, it will set endContext | to unknownContext. It may raise the 
-^H^ InvaiidEncoding error, 

The BackScanClosure and BackScanProc provide a way for the client to inform ReverseLop 
of the context in effect before a character set shift. If endContext | is unknownContext, 
then backScan.proc is called with a byte offset before which it desires a context and 
backScan.env. It should return a context for some position before the passed one, as well as 
the actual position corresponding to that context. Simple clients of ReverseLop need not 
provide a BackScanClosure. It is provided for clients that have information about location 
of character set changes within the reader. 

57.3 Usage/Examples 

57.3.1 Designing Interfaces with Readers 

Designing interfaces to use readers is more complicated than long strings. The biggest 
complication is the two-level allocation scheme involving readers reader bodies 
bytes. In most cases, the bytes are relatively static and are relatively easy to deal with. 
The main problem is determining whether to use a reader or a reader body. It helps to keep 
in mind the following guideline: keep reader bodies to describe the bytes. Save a pointer to a 
string by putting the reader body, not the reader, in the data structure. This way, one 
doesn't have to worry about who owns the storage for the reader body. Consider the 
following interface fragment: 

Handle: TYPE = long pointer to Object; 

Object: type = record [ 
next: Handle, 

count: CARDINAL, 

name: xstnng.ReaderBody]; 
AddAnother: procedure [name: xstring.Readerl; 

Instead of storing the name in the object as a reader, it is stored as a reader body. A reader 
is quickly generated when needed by the expression @h.name. 

Another guideline is for a procedure to take a reader and return a reader body. The idea is 
that passing readers as parameters reduces the number of words of parameters. Returning 
reader bodies allows the client to manage the storage for the reader body. 

A third guideline is that clients should be able to pass pointers to local reader bodies. If an 
implementation kept strings passed to it by saving readers, clients would have to allocate 
the reader body from permanent storage, not from the local frame. If implementations 
keep reader bodies instead of readers, passing @localReaderBody will not result in 
dangling pointers. For example, consider the following fictional procedure that renames a 
file: 

RenameFlle: procedure [oldName:xstnng.Reader| = { 
rb: xstring.ReaderBody; 
^""^ rb <— Somelnterface.GetNewName[]; 
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file <— Someinterface.LookupByName[oidName]; 
sonieinterface.Rename[file: file, newName: @rb]}; 

The procedure RenameFile takes a reader that it simply passes to another operation. 
While taking a reader body is equilvalent, it is more efficient to take a reader, 
particularily when strings are just being passed around. The operation GetNewName 
returns a reader body. If it returned a reader, it would have to define where the storage for 
the reader body was kept. Either it would have to be global, or it would have to be 
deallocated from a known place after RenameFile was done with it. It is just simplier to 
return reader bodies than to deal with the allocation problems of reader bodies. It is hard 
enough to make sure ownership of the bytes is handled correctly. The new name to the 
Rename operation is a pointer to a local reader body. Rename should copy the reader body 
(and the bytes) if it intends to save the characters. 

Warning: Designing interfaces that do not allow passing pointers to local reader bodies 
should be avoided. 

57.3.2 Using Readers 

One of the simple things to do with strings is to pass string literals. Because there is no 
compiler support for XString, it is harder to do. The code fragment below gives an example 
of how to pass string literals: 

GetUserCmFile: procedure returns [file: Someinterface.FileHandie] » { 
rb: xstring.ReaderBody <-xstring.FromSTRING["User.cm"L]; 
file ^Someinterface.LookupByNamefname: @rb]}; 

Looking at all the characters in a string for something like switch processing is another 
common operation: 

Options; TYPE = record [debug, verify, start: boolean <- false]; 

ParseSwitchesI : procedure [r: xstring.Reader] returns [options: Options] = { 
rb: xstring.ReaderBody <-xstring.Dereference[r]; 
c: xstring.Character; 
sense: boolean true; 

WHILE (c <— XString.Lop[@rbl) # XChar.nOt DO 
SELECT C FROM 

'd.ORD a > {options. debug <<— sense; sense «-true}; 
'v.ORD = > {options. verify <— sense; sense <— true}; 
's.ORD s > {options. start sense; sense true}; 
'-.ORD = > sense <- false; 
endcase = > sense <-true; 
endloop; 
return}; 

ParseSwitchesI uses Lop to look at each character of r and set the appropriate option. 
Because Lop changes the reader body to remove the first character, ParseSwitchesI uses 
Dereference to copy the reader body to a local variable. 
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The operations Lop, Run, ScanForCharacter, and Scan all update the reader body of their 
reader parameter. If the reader body must not be altered, it should be copied as in the 
above example. 

ParseSwitchesZ: procedure (r: xstring.Reader] returns [options: Options] = { 
sense: boolean «-true; 
proc: xstring.MapCharProc = { 

SELECT C FROM 

'd.ORD a > {options. debug <— sense; sense <— true}; 
'v.ORD = > {options. verify <— sense; sense <— true}; 
's.ORD a > {options.start <- sense; sense <- true}; 
'-.ORD = > sense false; 
ENDCASE a > sense<-TRUE; 

RETURN[stOp: FALSE]}; 

[] «-xstring.Map(r: r, proc: proc]; 

RETURN}; 

ParseSwitches2 uses Map to look at each character of r and set the appropriate option. 



57.3.3 Simple Parser Example 

Below is a simple program that accepts a sequence of characters from a procedure and 
parses them into tokens. It collects characters one a a time and appends them to the writer 
buffer. If the string of characters is empty, it returns a keyword token of invalid. If the 
first character is a digit, it returns a number token, converting the string into the number. 
Otherwise it compares the string with the four keywords. If it is not a keyword, it copies 
the string from the buffer to a new reader and returns the id token. 



— Example.mesa 



DIRECTORY 

XString using [ 

AppendChar, Character, ClearWriter, Empty, Equal, First, InvalidNumber, 
NewWriterBody, OverFlow, Reader, ReaderBody, ReaderFromWriter, 
ReaderToNumber, WriterBody]; 



Example: PROGRAM IMPORTS XString = { 
OPEN XString; 

TokenClass: type = {keyword, id, number}; 

Keyword: TYPE = {begin, end, do, endloop, eof, invalid}; 

Token: type a record [ 

SELECT class: TokenClass FROM 

keyword a > [keyword: Keyword], 

id a > [id: ReaderBody], 

number = > [number: long integer], 

ENDCASE]; 



Input: TYPE a PROCEDURE RETURNS [Character]; 
eof, space: Character a . . . ; 

keywords: long descriptor for array Keyword[begin.. endloop] of ReaderBody = 
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zone: uncounted zone 

buffer: WriterBody NewWriterBody[maxLength: 40, z: zone] ; 

Parse: PROCEDURE [input: Input] RETURNS [token: Token] a { 
r: Reader ReaderFromWriter[@buffer]; 
c: Character; 
C!earWriter[buffer]; 

DO 

SELECT (C «- input[]) FROM 

space B > exit; 

eof a > RETURN[[keyword[iF Empty[r] then invalid else eof]]]; 
ENDCASE = > AppendChar[@buffer, cj; 

ENOLOOP; 

IF Empty[r] then RETURN[[keyword[invalid]]; 
IF First[r] in ['0.ord..'9.ord] then { 

token <— [number[ReaderToNumber[r, 10 ! 

InvalidNumber, Overflow = > {token <- [keyword[invalidl]; continue}]]]; 

return}; 

select TRUE FROM 

Equai[r, @keywords[begin]] = > token «— [keyword[begin]]; 
Equai[r, @keywords[end]] = > token «— [keyword[end]]; 
Equal[r, @keywords[do]] = > token <- [keyword[do]]; 
Equal[r, @keywords[endloop]] = > token [keyword[endloop]]; 
ENDCASE ■ > 

token <-[id[CopyToNewReaderBody[r: r, z: zone]]]; 
return}; 
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57.4 Index of Interface Items 



Item 


Page 


Item 


Page 


AppendChar: procedure 


12 


FromNSString: procedure 


7 


AppendExtensionlf Needed: procedure 


13 


FromSTRING: procedure 


7 


AppendReader: procedure 


12 


InitBreakTable: procedure 


11 


AppendStream: procedure 


13 


InsufficientRoom: signal 


13 


AppendSTRING: procedure 


13 


InvaiidEncoding: error 


6 


BackScanClosure: type 


14 


InvalidNumber: signal 


10 


BackScanProc: type 


14 


Lop: PROCEDURE 


5 


Block: procedure 


14 


Map: PROCEDURE 


6 


BreakCharOption: type 


11 


MapCharProc: type 


6 


BreakTabie: type 


11 


MewWrlterBody: procedure 


8 


BreakTableObject: type 


11 


NSStringFromReader: procedure 


14 


Byte: type 


4 


NthCharacter: procedure 


5 


ByteLength: procedure 


5 


nuilReaderBody: ReaderBody 


4 


Bytes: type 


4 


nullWriterBody: WriterBody 


4 


ByteSequence: type 


3 


Overflow: signal 


10 


CharacterLength: procedure 


5 


Piece: procedure 


13 


ClearWriter: procedure 


8 


Reader: type 


3 


Compare: procedure 


10 


ReaderBody: type 


3 


CompareStringsAndStems: procedure 


10 


ReaderFromWriter: procedure 


6 


ComputeEndContext: procedure 


11 


Readerlnfo: procedure 


5 


Context: type 


2 


ReaderToNumber: procedure 


10 


CopyReader: procedure 


7 


ReadOnlyBytes: type 


3 


CopyToNewReaderBody: procedure 


7 


Relation: type 


10 


CopyToNewWriterBody: procedure 


9 


ReplacePiece: procedure 


14 


Dereference: procedure 


5 


ReverseLop: procedure 


14 


DescribeReader: courier. Description 


12 


ReverseMap: procedure 


14 


DescribeReaderBody: Courier.Description 12 


Run: PROCEDURE 


12 


Empty: procedure 


5 


Scan: procedure 


11 


emptyContext: Context 


3 


ScanForCharacter: procedure 


11 


Equal: procedure 


9 


SortOrder: type 


9 


Equivalent: procedure 


9 


StopOrNot: type 


11 


Error: error 


6 


unknownContext: Context 


3 


ErrorCode: type 


6 


VaiidateReader: procedure 


12 


ExpandWriter: procedure 


9 


vanillaContext: Context 


3 


First: procedure 


5 


Writer: type 


4 


FreeReaderBytes: procedure 


7 


WriterBody: type 


4 


FreeWriterBytes: procedure 


9 


WriterBodyFromBlock: procedure 


8 


FromBlock: procedure 


7 


WriterBodyFromNSString: procedure 


8 


FromChar: procedure 


7 


WriterBodyFromSTRING: procedure 


8 






Writerlnfo: procedure 


8 
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58.1 Overview 

The XTime interface provides functions to acquire and edit times into strings or strings 
into times. It provides the same function as the XDE Time interface but deals with 
xstring. Readers instead of long strings. 

58.2 Interface Items 

58.2.1 Acquiring Time 

Current: PROCEDURE returns (time: System. GreenwichMeanTime]; 

Current returns the current time. 

ParseReader: procedure [ 

r: xstring.Reader, treatNumbersAs: TreatNumtaersAs <-dayMonthYear] 
returns [time:systeni.GreenwichMeanTime, notes: Notes, length: cardinal]; 

ParseWithTemplate: procedure [r, template: xstring.Reader] 

RETURNS [time: System. GreenwichMeanTime, notes: Notes, length: cardinal]; 

TreatNumbersAs: type = {dayMonthYear, monthDayYear, yearMonthDay, 
yearDayMonth, dayYearMonth, month YearDay}; 

The ParseReader procedure parses the reader, r, and returns a GMT time according to the 
Pilot standard. treatNumbersAs indicates how to interpret r. ParseWithTemplate parses r 
according to template, template serves as an interpreter for deriving time fields from r, 
see § 58.3. The date synta.x is a somewhat less restrictive version of RFC733; full RFC733 
is recognized, plus forms like "month day, year", "mm/dd/yy", and variations with Roman 
numerals used for the month. The form "year month day" is also accepted if the year is a 
full four-digit quantity. Forms with "~" instead of significant space are also acceptable, as 
well as forms in which a delimiter (space or "-") can be elided without confusion. The time 
is generally assumed to be in RFC733 format, optionally including a time zone 
specification. In addition, am or pm may optionally appear following the time (but 
preceding the time zone, if any), notes is interpreted as described below, length indicates 
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the number of characters consumed by the parser; that is, it is the index of the first 
character of the argument that was not examined by the parser. This procedure can raise 
the error Unintelligible. 

Notes: TYPE a {normal, noZone, zoneGuessed, noTime, timeAndZoneGuessed}; 

Notes is used as one of the return values from the call on ParseReader. normal means the 
value returned is unambiguous; noZone means that a time-of-day was present, but 
without a time zone indication. (The local time zone as provided by 
System. LocalTimeParameters is assumed.) zoneGuessed is returned instead of noZone if 
local time parameters are not available, and the time zone is assumed to be Pacific Time 
(standard or daylight time is determined by the date). noTime and timeAndZoneGuessed 
are equivalent to noZone and zoneGuessed respectively, where the time is assumed to be 
00:00:00 (local midnight). 

Unintelligible: error [vicinity: cardinal]; 

If ParseReader cannot reasonably interpret its input as a date. Unintelligible is raised; 
vicinity gives the approximate index in the input string where the parser gave up. 



58.2.2 Editing Time 



Append: procedure [ 

w: xstring.Writer, time: System. GreenwichMeanTime «-defaultTime, 
template: xstring.Reader «-da.teAndTime, Itp: LIP ^ useSystem]; 

Append appends the time in human-readable form to w. template determines which fields 
are appended. Itp is used to provide the local time parameters (discussed below). 

Format: procedure [ 

xfh: XFormat.Handle ^NIL, time: System. GreenwichMeanTime «-defaultTime, 
template: xstring.Reader <-dateAndTime, Itp: LTP «- useSystem]; 

Format converts time to a string by calling XTime.Append using template to specify which 
template to use. xfh.proc is then called. If time is defaulted, the current time is used. 

Pack: procedure [unpacked: Unpacked, useSystemLTP: boolean «-true] 
returns [time: System. GreenwichMeanTime]; 

Pack converts unpacked into the Pilot-standard System.GreenwichMeanTime. 
useSystemLTP indicates that Pack should use the system's parameters. If the local time 
parameters are not available to Pilot, System. LocalTimeParametersUnknown is raised. If 
unpacked is invalid, Invalid is raised. 

Packed: type = System.GreenwichMeanTime; 

Packed is retained for compatability. 

Unpack: procedure [ 

time: System.GreenwichMeanTime <—defaultTime, Itp: LTP «- useSystem] 
returns [unpacked: Unpacked]; 
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Unpack converts time into its unpacked representation. If time is defaulted, the current 
time is used. Itp provides local time parameters. If the local time parameters are not 
available to Pilot, System. LocalTimeParametersUnknown is raised. If time is invalid, 
Invalid is raised. 

Unpacked: TYPE a record[ 

year: [0..2104], month: [0..12), day: [0..31], 

hour: [0..24), minute: [0..60), second: [0..60), 

weekday: [0..6L dst: boolean, zone: System.LocalTimeParameters]; 

Unpacked values record dates by their pieces. The fields are filled by Unpack, described 
above, which operates on the time and date as kept internally by Pilot, year = 0 
corresponds to 1968. For month, January is numbered 0, I, etc. Days of the month have 
their natural assignments. For weekday, Monday is numbered 0. dst indicates Daylight 
Standard Time, zone indicates time zones. 

LIP: TYPE a REC0RD[ 

r: SELECT t: * from 
useSystem a > (], 

useThese = > [Ipt: System.LocalTimeParameters]] 
endcase]; 

LTP is used to pass local time parameters to several procedures. Usually they are defaulted 
to the system's parameters. 

Invalid: error; 

58.2.3 Useful Constants and Variables 

dateAndTime: xstring.Reader; 
dateOnly: xstring.Reader ; 
timeOnly: xstring.Reader; 

These variables are templates that are supplied by XComSoftMessage for use in the 
Append operation. 

defaultTime: System, GreenwichMeanTime = System.gmtEpoch; 

defaultTime always means the current time. 

useSystem: useSystem LTP = (useSystem(]]; 
useGMT: useThese LTP = [useThese([west, 0,0,0,0]]]; 

These local time parameters are e.xported for client convenience. 
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58.3 Usage/Examples I 

58.3.1 ParseReader Template Definitions 

The template for times is a reader with fields, using the standard definiton of naming 
fields, that is, a number enclosed by angle brackets. The definition of the fields for times 
are: 



<1> 


Month as a number* 


<2> 


Day as a number* 


<a> 


Year as a four-digit number 


<4> 


Year as a two-digit number 


<5> 


Month name. 


<6> 


Month name with a maximum of three characters 


<7> 


Hour as digits in range [0..12)* 


<8> 


Hour as digits in range [0..24)* 


<9> 


Minutes, always two digits, zerofilled (e.g., 23, 04) 


<10> 


Seconds, always two digits, zerofilled (e.g., 23, 04) 


<11> 


Day of week 


<12> 


Time zone 


<13> 


AM or PM 



* If the number begins with a 0, the number is zerofilled to two digits. 
Examples 

<2>-<6>-<4> <7>:<9> 18-Nov-83 8:36 

<2> <5> <3> 18 November 1983 

<2>-<6>-<4> <7>;<9>:<10> <12>(<11>) 18-Nov-83 08:36:42 PST (Friday) 

<7>:<9> <13> 8:36AM 

< 08 X 9 > hrs 0836 hrs 



58.3.2 Example 

— Data structure to record time in botti Packed and Unpacked form. 
Data: type = record [ 

startTime: xstnng.ReaderBody <— xstring.nuilReaderBody, 
endTime: xstring.ReaderBody <-xstring.nuilReaderBody, 
pStartTime: xTime.Packed ^ System. gmtEpoch, 
pEndTime: XTime.Packed System. gmtEpoch]; 

— Retrieves, unpacks, stores, and displays t/ie time. 
GetAndDispiayTime: pROC[packTime: XTime.Packed] = { 

time: xTime. Unpacked "(-xTime.UnpackEpackTime]; 

TimeDispiay [time. year, time.month, time.day]; | 

}; 
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ParseTimes:PROc[data:Data] a { 

data.pStartTime «-xTime„ParseReacler[@clata.startTime ! 

XTime. Unintelligible = > Error[BadStartTime, vicinity]].time; 
data.pEndTime <— xTime.ParseReader[@data.endTime ! 

xTime.Unsntelligibie = > Error[BadEndTime, vicinity]].time; 

}; 

-- Parses time into an xstring.ReaderBody 
PackedToString: PROC[time: System.GreenwichMeanTime] 

RETURNS [rb:XString.ReaderBody <-XString.nullReaderBody] = { 

template: xstring.ReaderBody <-xstrmg.FromSTRING[ 
"<2>-<6>-<4> <8>:<9>"L]; 

wb: xstring.WriterBody <~xstring.NewWriterBody[24, zone]; 

xTime.Append[ @wb, time, ©template ]; 

rb ^xstring.CopyToNewReaderBody[xstring.ReaderFromWriter[@wb], zone]; 
xstring.FreeWriterBytes[<|pwb]; 

}; 
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58.4 Index of Interface Items 




Item 


Page 


Append: procedure 


2 


Current: procedure 


1 


dateAndTime: xstring.Reader 


3 


dateOnly: xstring.Reader 


3 


defaultTime: constant 


3 


Format: procedure 


2 


Invalid: error 


3 


LTP: type 


3 


Notes: type 


2 


Pack: procedure 


2 


Packed: type 


, 2 


ParseReader: procedure 


1 


ParseWith Template: procedure 


1 


timeOnly: xstring.Reader 


3 


TreatNumbersAs: type 


1 


Unintelligible: error 


2 


Unpack: procedure 


2 


Unpacked: type 


3 


useGMT: constant 


3 


useSystem: constant 


3 
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59.1 Overview 

The XToken interface provides general scanning and simple parsing facilities for 
collecting tokens from a character input stream. 

The basic data structure is the Object, which encapsulates the source of characters to be 
parsed. It contains a procedure that returns the next character in the input stream and 
the final character that is read from the input stream. 

The basic operations collect characters from the input stream into tokens. Clients can 
define arbitrary token classes by using filters. Clients can define their own filters or use 
one of the standard filters provided by XToken. Frequently, some portion of the input 
stream, such as blanks, are only delimiters and are usually skipped when collecting a 
token. The type SkipMode defines the options for skipping characters. Quoted tokens are a 
feature provided by XToken. By using procedures to define opening- and closing-quote 
characters, XToken allows the client to define a large number of quoting schemes. Several 
common quote procedures are supplied. 

XToken provides operations that collect standard tokens such as boolean and numeric 
values. It also provides built-in handles that understand xstring. Readers and 
Stream. Handles as sources of characters. 

Operations that return a reader body allocate their storage from the implementation's 
own heap. Clients should call FreeTokenString to release this storage. 

59.2 Interface Items 

59.2.1 Character Source Definitions 

Handle: TYPE = long pointer to Object. 

Object: TYPE 3 MACHINE DEPENDENT RECORD [ 

getChar(0):GetCharProcType, break(l): xchar.Character <-ol; 
GetCharProcType: TYPE = procedure [h: Handle] returns [c: xchar.Character]; 
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The Object encapsulates the source of characters to be parsed. The XToken package uses 
the getChar field to obtain the stream of characters. It assumes that the source has been 
exhausted when getChar returns xchar.null or xchar.not. XToken uses the break field to 
record the final character that it reads. It records the final character because there is no 
way to put back a character into the character source. It must read one character beyond 
the token it is parsing to ensure that it has reached the end of the input. If it simply 
returned the token, this character would be lost. Since the XToken package stores the last 
character in the Object, that character is available to the client. The client can ignore it, 
inspect it to decide what to parse next, or put it back into the character source. 

A GetCharProcType provides a stream of characters to be parsed. It should return either 
xchar.null or xchar.not when the stream of characters has been exhausted. The Handle is 
passed into the GetCharProcType so that a client can hide instance data in his object. 
Although there is not an instance data field in Object, the client could loophole a pointer 
to a larger record that contained its data. 

59.2.2 Filter Definitions 

FilterProcType: TYPE = procedure [ 

c: xchar.Character, data: FilterState] returns [InCiass: boolean]; 

FilterState: TYPE = long pointer to StandardFilterState; 

StandardFilterState: TYPE = array [0..2) of unspecified; 

A FilterProcType is the mechanism by which a client defines classes of characters. 
Procedures that use filters will call them once for each candidate character. The filter 
should return true if the character is in the class and false otherwise. The FilterState 
permits the filter to maintain the state of the parse. Operations that require a 
FilterProcType and FilterState, will initialize the StandardFilterState to all[0] If the filter 
requires filter state but data is nil, the signal Nil Data should be raised. 

Some clients' filters may need more than two words of state for their filter. In that case 
they should define a record that first contains a StandardFilterState, then define the 
additional space they need, and then loophole the filter state to a pointer to the record they 
defined. 

59.2.3 Skip Mode Definitions 

SkipMode: type = {none, whiteSpace, nonToken}; 

SkipMode controls what characters an operation will skip before collecting a token. 

none The term none means no characters should be skipped, and the token 

should start with the next character. 

whiteSpace The term whiteSpace means characters (space, carriage return, and 
tab) should be skipped before collecting the token. 

nonToken The term non Token means any characters that are not legal token 

characters should be skipped before collecting the token. 
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59.2.4 Quoted Token Definitions 

QuoteProcType: type = procedure [ 

c: xchar.Character] returns [closing: xchar.Character]; 

nonQuote: xchar.Character =» . . . , 

QuoteProcType defines the procedure used by MaybeQuoted to recognize quoted tokens. 
If c is a quote character, it should return the corresponding closing-quote character. If c is 
not a quote character, it should return nonQuote. 



59.2.3 Built-in Handles 



ReaderToHandte: procedure [r: xstnng.Reader] 
RETURNS [h: Handle]; 

ReaderToHandle creates a Handle whose source of characters are the characters in r. The 
bytes of r are not copied, so clients are responsible for synchronizing access to the reader 
with the XToken package. 

FreeReaderHandle: procedure [h: Handle] returns [nil: Handle]; 

FreeReaderHandle destroys a Handle created by ReaderToHandle, It does not destroy the 
underlying reader. It returns nil. 

StreamToHandle: procedure [s: stream. Handle] returns [h: Handle]; 

StreamToHandle creates a Handle whose source of characters is a stream. The stream 
should signify the end of characters by raising the signal Stream. EndOfStream. 

FreeStreamHandle: procedure [h; Handle] returns [s: stream.Handle]; 

FreeStreamHandle destroys a Handle created by StreamToHandle. It returns the 
underlying stream. 



59.2.6 Boolean and Numeric Tokens 

Boolean: procedure [h: Handle, signaiOnError: boolean 4- true] returns [true: boolean]; 

Boolean parses the next characters of the source as a boolean constant. Valid Boolean 
values are "TRUE" or "FALSE," but unlike the Mesa language, case does not matter 
("true" and "false" are also acceptable). In case of a syntax error, the signal SyntaxError is 
optionally raised. If signaiOnError is false, or SyntaxError is resumed, then false is 
returned for a syntax error. This procedure skips leading white space. 

Number: procedure [h: Handle, radix: cardinal, signaiOnError: boolean <— true] 
RETURNS [u: long unspecified]; 

Number parses the next characters of the source as a number in radix radix. Numbers 
have the format specified in xstrlng.ReaderToNumber. In case of a syntax error, the signal 
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SyntaxError is optionally raised. If signalOnError is false, or SyntaxError is resumed, zero 
is returned for a syntax error. This procedure skips leading white space. 

Decimal: procedure [ 

h: Handle, SignalOnError: boolean <- true] returns [1: long integer]; 

Decimal is just like Number, but with a radix of 10. 

Octal: procedure [ 

h: Handle, signalOnError: boolean <- true] returns [c: long cardinal] ; 

Octal is just like Number, but with a radix of 8. 



Filtered: procedure [ 

h: Handle, data: FilterState, filter: FilterProcType, skip: SkipMode whiteSpace, 
temporary: boolean <- true] 
RETURNS [value: xstnng.ReaderBody]; 

Filtered collects the token string defined by the client's filter. If the client-instance data 
parameter data is not nil, the first two words of data are set to zero before any calls are 
made to filter, filter is called with data once on each character until it returns false. The 
string returned, which may be xstring.nullReaderBody, must be freed by calling 
FreeTokenString. Leading characters are skipped according to the value of skip. If 
temporary is true, it is assumed that the string will be freed shortly, and.no effort is made | 
to use the minimum storage for it. If temporary is false, the minimum amount of storage 
is used, filter may raise NilData. 

FreeTokenString: procedure [s: xstn'ng. Reader] returns [nil: xstring.Reader «-nil]; 

FreeTokenString frees bytes of the reader. It is used to free the strings allocated by 
Filtered, Item, and MaybeQuoted. It returns nil. 

Item: procedure [ 

h: Handle, temporary: boolean <- true] returns [value: xstnng.ReaderBody]; 

Item returns the next token delimited by white space. Leading white space is skipped and 
the characters are collected until another white-space character is encountered. The 
string returned must be freed by calling FreeTokenString. If temporary is true, it is 
assumed that the string will be freed shortly, and no effort is made to use the minimum 
storage for it. If temporary is false, only as much storage is used for the string as is 
needed. 

MaybeQuoted: PROCEDURE! 

h: Handle, data: FilterState, filter: FilterProcType «- NonWhiteSpace, 
isQuote; QuoteprocType «(— Quote, skip: SkipMode <— whiteSpace, 
temporary: boolean true] 
RETURNS [value: xstring.ReaderBody]: 



MaybeQuoted returns the next quoted token. The first candidate character is passed to 
isQuote, which either returns nonQuote or the closing-quote character. If a closing-quote 
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character other than nonQuote is returned, characters are collected in the token until the 
closing quote is encountered. If the input is exhausted before the closing quote is 
encountered, the signal UntermlnatedQuote will be raised. If it is resumed, 
MaybeQuoted returns the token collected up until that point. The closing-quote character 
may be included in the token by including two instances of the character in the input; that 
is, if MaybeQuoted encounters two closing-quote characters in a row, it will insert one 
closing-quote character in the token rather than terminating the token on the first closing 
quote. The outer quote characters are not part of the token and are discarded. If nonQuote 
is returned from the isQuote procedure, the filter is used to collect characters the same 
way it is used in Filtered: filter is called with client-instance data parameter data once on 
each character until it returns false. In either case (quoted or filtered), the break character 
returned in the Handle is the character following the token. 

Leading characters are skipped according to the value of skip. 

If temporary is true, it is assumed that the string will be freed shortly and no effort is 
made to use the minimum storage for it. If temporary is false, only as much storage is used 
for the string as is needed. The string returned must be freed by calling FreeTokenString. 

Skip: procedure [ 

h: Handle, data: FilterState, filter: FilterProcType, skiplnClass: boolean <- true]; 

Skip is used to skip over characters. A filter is provided to define the class of characters, 
and the boolean skiplnClass indicates whether the characters to be skipped are those 
accepted by the filter or those rejected by it. If the client-instance data parameter data is 
%^ff not NIL, the first two words of data are set to zero before any calls are made to filter. If data 

is NIL and filter references data, the signal NilData should be raised. 

59.2.8 Signals and Errors 

SyntaxError: signal [r: xstring.Reader]; 

The resumable signal SyntaxError can be raised if incorrect syntax is encountered by 
Boolean, Decimal, Number, or Octal. In each case, resuming the signal causes the 
procedure to return a default value (described in the discussion of the various procedures). 
The reader parameter is the token collected that has the wrong syntax. 

NilData: signal; 

Procedures that take a FilterProcType argument also take an argument that is a pointer to 
client instance data. If the client has no need for instance data, it can pass a nil as the 
instance data pointer. If a FilterProcType attempts to access the client-instance data, but 
the client passed in nil instead of a pointer to instance data, the signal NilData should be 
raised. Implementors of FilterProcTypes are strongly encouraged to check for nil and raise 
this condition if they use client- instance data. 

UnterminatedQuote:siGNAL; 

The resumable signal UnterminatedQuote is raised from MaybeQuoted if the getChar 
procedure of the Handle returns xchar.not or xchar.null before the terminating quote 
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character has been read. If the signal is resumed, MaybeQuoted will return as if it had 
read a closing-quote character. 



59.2.9 Built-in Filters 



Alphabetic: FilterProcType; 

Alphabetic defines the class of alphabetic characters; that is, the characters °a through "z 
and 'A through 'Z. This procedure requires no filter state. 



AlphaNumeric: FilterProcType; 

AlphaNumeric defines the class of alphanumeric characters, that is, the characters 'a 
through 'z, 'A through 'Z, and '0 through '9. This procedure requires no filter state. 

Delimited: FilterProcType; 



When Delimited is passed to a procedure such as Filtered, the value of skip passed along 
with it must be nonToken. It will skip leading white space, then define the first character 
of the token to be both the opening-quote character and the closing-quote character, 
returning all characters occurring between the first and second appearance of that 
character. 

Line: FilterProcType; 

Line defines a class containing all characters except the carriage return. It can be used to 
collect a line of information. This procedure requires no filter state. 

NonWhiteSpace: FilterProcType; 

NonWhiteSpace FilterProc defines all characters that are not white space; that is, 
WhiteSpace[char] = --NonWhiteSpace(char]. This procedure requires no client data (data 
may be NIL.) 

Numeric: FilterProcType; 

Numeric defines the class of numeric characters (the characters '0 through '9) This 
procedure requires no filter state. 

Switches: FilterProcType; 

Switches can be used to collect switch characters. It accepts the characters , '-, and 
alphanumeric characters. This procedure requires no filter state. 

WhiteSpace: FilterProcType; 

The WhiteSpace FilterProcType defines the white space characters. This filter is used by 
Token for skipping white space. This procedure requires no filter state. 
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59.2.10 Built-in Quote Procedures 
Brackets: QuoteProcType; 

Brackets recognizes the following sets of matching open/close quote pairs: (),[],{}, and < 
>. 



Quote: QuoteProcType; 

Quote recognizes single quote and double quote. 



59.3 Usage/Examples 



59.3.1 Collecting Tokens 



The following example collects name and number pairs from a stream. It uses the built-in 
stream handle provided by XToken for the source of characters. It uses the Item operation. 

ProcessltemsFromStream: PROCEDURE [stream: Stream. Handle] s { 
tH: xToken.Handle <- xToken.HandleFromStream[stream]; 
name: xstring.ReaderBody <-XToken.ltem[tHl; 
number: long integer; 
UNTIL xstring. Empty [@name] do 

number <~ XToken.Decimal[h: tH, signaiOnEirror: false]; 

Processltem[@name, number]; — do work 

[] <- XToken.FreeTokenString[@name]; 

name <- xToken.ltem[tH]; 

ENDLOOP; 

[] <- xToken.FreeStreamHandle[tH]}; 

The following example demonstrates how the XToken interface could be used to parse 
input into tokens, optionally followed by switches. In this context, tokens and switches are 
defined to be any sequence of non-white-space characters, not including the slash 
character (/). 

GetToken: procedure returns [token, switches: xstring.ReaderBody] = 

BEGIN 

get: xToken.GetCharProcType = {RETURN[GetCommandLineChar[]l}; 
getToken: XToken.Object [getChar: get, break: xchar.not]; 
slash: xchar.Character = V.ord; 
MyFllter: xToken.FilterProcType » { 

RETURN[SELECT true FROM 

xToken.WhlteSpace[c, data], c = xchair.not = > false, 

C a slash a > FALSE, 
ENDCASE a > TRUE]}; 

token «-XToken.Filtered[@getToken, nil, MyFilter]; 

IF getToken. break = slash then switches <-xoken.Filtered[@getToken, nil, MyFilter] 

ELSE switches <e- xstring. nullReaderBody; 

end; 
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We can extend this example so that the token is defined to be either a sequence of non- 
white-space characters or a sequence of characters, containing white space characters, 
between double quotes. 

GetToken: procedure returns [token, switches: xstring.ReaderBody] = 

BEGIN 

get: xToken.GetCharProcType = {RETURN[GetCommandLineCharni}; 
getToken: xToken. Object <— [getChar: get, break: xchar.not]; 
slash: xchar.Character = V.ord; 
doubteQuote: xchar.Character a '".ord; 
isQuote: XToken.QuoteProcType a { 

RETURN[iF c = doubleQuote then c else xToken.nonQuote]}; 
MyFilter: XToken.FilterProcType » { 

return(select true from 

xToken.WhiteSpace[c, data], c = xchar.not a > false, 

C a slash a > FALSE, 

endcase a > true]}; 
token <--xToken.MaybeQuoted[@getToken, nil, MyFilter, IsQuote]; 
iFgetToken.break a slash THEN switches <-xoken.Filtered(@getToken, NIL, MyFilter] 
ELSE switches xstnng.nullReaderBody; 
end; 
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Appendix A 



System TIP Tables 



A.l Overview 



The TIP Tables used by ViewPoint are listed on the following pages to provide the 
programmer with a list of the productions available in the general purpose tables. The 
Normal tables described in §A.2.1 are placed in the TIPStar watershed at boot time and are 
therefore available for use by application programs. See the TIPStar interface for further 
information about the TIPStar watershed. Clients are encouraged to use the productions in 
the Normal tables whenever possible rather than generating new tables. Examples of use 
are provided in §A.3. 



A.2 Tables 



A.2.1 Normal Tables 



The set of Normal tables (NormalMouse.TIP, NormalSoftKeys.TIP, NormalKeyboard.TIP, 
NormaiSideKeys.TIP, NormalBackstop.TIP) are registered at startup and pushed into the list of 
TIP Tables at the appropriate TIPStar placeholder (mouseActions, softKeys, blackKeys, 
sideKeys, backstopSpecialFocus). (See TIPStar for further explanation about placeholders.) 
The set of Normal tables provides productions for all possible user input. Table entries are 
divided up into logical groups corresponding to the placeholder the table will be pushed 
onto. Thus input actions pertaining to the mouse (Point Down, Adjust Down, etc.) appear 
in the NormalMouse.TIP table and NormalMouse.TIP is pushed onto the mouseActions 
placeholder. Key actions from the side function key group that are directed at the input 
focus (MOVE Down, COPY Down, etc.) appear in the NormaiSideKeys.TIP table and are pushed 
onto the sideKeys placeholder. Key actions such as the alphanumeric keys (A Down, 3 
Down, etc.) appear in the NormalKeyboard.TIP table and are pushed onto the blackKeys 
placeholder. Key actions pertaining to the row of function keys at the top of the keyboard 
(CENTER Down, BOLD Down, etc.) appear in the NormalSoftKeys.TIP table and are pushed onto 
the softKeys placeholder. Key actions from the side function key group that are not 
directed at the input focus (KEYBOARD Down, HELP Down) appear in the NormalBackstop.TIP 
table and are pushed onto the backstopSpecialFocus placeholder. 

At the end of ViewPoint boot sequence, the list of tip. Tables in ViewPoint will appear as in 
Fig. A-1. 
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mouseActions placeholder 



NormalMouse.TIP 



keyOverrides placeholder 



softKeys placeholder 



NormalSoftKeys.TIP 



keyboardSpecific placeholder |^ 



keyboardplaceholder 



Normal Keyboard -TIP 



sideKeys placeholder 



NormalSideKeys.TIP 



backstopSpecial Focus placeholder 



NormalBackstop.TIP 



NIL 



Figure A. 1 TIP Tables after boot 

-File: NormalBackstop.TIP last edit: 23-Oct-84 20:20:59 
"This file is the NormalBackstop for the 8010 

[DEF,lfShift,(SELECT ENABLE FROM 
LeftShift Down = > '1; 
RightShift Down = > "1 ; 
Key47 Down = > "1 ; - JLevellV keyboard 
A12Down = > '1; -- JLevellV keyboard 

ENDCASE = > "2)1 
SELECT TRIGGER FROM 

FONT Down = > (lfShift,ShiftFontDown,FontDown]; 
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FONT Up => [IfShift.ShiftFontUp.FontUp]; 

KEYBOARD Down => [lfShift,ShiftKeyboardDown,KeyboarclDown]; 

KEYBOARDup => [lfShift,ShiftKeyboardUp,KeyboardUp]; 

HELP Down => [IfShift.ShiftHelpDown.HelpDown]; 

HELP Up => [lfShift,ShiftHelpUp,HelpUp]; 

STOP Down => [lfShift,ShiftStop,Stop]; 

STOP Up => [lfShift,ShiftStopUp,StopUp]; 



ENDCASE.. 



A 



System TIP Tables 



-File: NormalBackstop.TIP last edit: 21-Jun-85 15:00:42 
"This file is the NormalBackstop for the 6085. 

[OEF,lfShift,(SELECT ENABLE FROM 
LeftShift Down = > ~1 ; 
RightShift Down = > "1 ; 

LeftShiftAit Down = > ' 1 ; -- JLevellV keyboard 
RightShiftAit Down = > "1 ; — JLevellV keyboard 

ENDCASE = > '2)1 
SELECT TRIGGER FROM 

KEYBOARD Down => [lfShift,ShiftKeyboardDown,KeyboardDown]; 
KEYBOARD Up = > [lfShift,ShiftKeybGardUp,KeyboarciUp]; 
STOP Down = > [lfShift,ShiftStop,Stopl; 
STOP Up = > [IfShift.ShiftStopUp.StopUp]; 

ENDCASE... 
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--F/7e; NormalKeyboard.TIP /ast ed/t; 28-Nov'84 17:05:52 

[OEFjf Shift,(SELECT ENABLE FROM 
LeftShift Down = > -1 ; 
RightShift Down = > ~1; 
Key47 Down = > ~i ; — JLevellV keyboard 
A12 Down = > -1 ; — JLevellV keyboard 

ENDCASE = > ~2)] 
SELECT TRIGGER FROM 

BS Down = > [IfShift, BackWord, Backspace]; 
Return Down = > (IfShift, NewLine, NewParagraph]; 



Zero Down = > BUFFEREDCHAR; 
One Down = > BUFFEREDCHAR; 
Two Down = > BUFFEREDCHAR; 
Three Down = > BUFFEREDCHAR; 
Four Down = > BUFFEREDCHAR; 
Five Down = > BUFFEREDCHAR; 
Six Down = > BUFFEREDCHAR; 
Seven Down = > BUFFEREDCHAR; 
Eight Down = > BUFFEREDCHAR; 
Nine Down = > BUFFEREDCHAR; 

A Down = > BUFFEREDCHAR; 
BDown = > BUFFEREDCHAR; 
CDown = > BUFFEREDCHAR; 
DDown = > BUFFEREDCHAR; 
E Down = > BUFFEREDCHAR; 
F Down = > BUFFEREDCHAR; 
G Down = > BUFFEREDCHAR; 
H Down 3 > BUFFEREDCHAR; 
I Down = > BUFFEREDCHAR; 
J Down s > BUFFEREDCHAR; 
K Down = > BUFFEREDCHAR; 
L Down s > BUFFEREDCHAR; 
M Down = > BUFFEREDCHAR; 
N Down = > BUFFEREDCHAR; 
0 Down = > BUFFEREDCHAR; 
P Down = > BUFFEREDCHAR; 
Q Down = > BUFFEREDCHAR; 
RDown = > BUFFEREDCHAR; 
S Down = > BUFFEREDCHAR; 
TDown = > BUFFEREDCHAR; 
U Down = > BUFFEREDCHAR; 
VDown = > BUFFEREDCHAR; 
WDown = > BUFFEREDCHAR; 
X Down = > BUFFEREDCHAR; 
Y Down = > BUFFEREDCHAR; 
Z Down = > BUFFEREDCHAR; 
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CloseQuote Down = > BUFFEREDCHAR; 
Comma Down = > BUFFEREDCHAR; 
Minus Down = > BUFFEREDCHAR; 
Equal Down = > BUFFEREDCHAR; 
LeftBracket Down = > BUFFEREDCHAR; 
Period Down = > BUFFEREDCHAR; 
OpenQuote Down = > BUFFEREDCHAR; 
RightBracket Down = > BUFFEREDCHAR; 
Semicolon Down = > BUFFEREDCHAR; 
Space Down = > BUFFEREDCHAR; 
Slash Down = > BUFFEREDCHAR; 

PARATAB Down = > TabOoWH; 

TAB Down = > ParaTabOowH; 

LOCK Down = > LOCkDOWII; 
LOCKUP = > Lockup; 

All Down = > BUFFEREDCHAR; -- JLevellV keyboard 

A8 Down = > ASDown; -- JLevellV keyboard 
A9 Down = > A90own; — JLevellV keyboard 

— nonexistent keys 

AlODown => AlODOWn; 

01 Down = > DIDown; 

02 Down = > 02 Down; 
LI Down = > LIDOwn; 
L4 0own = > L4DOwn; 
L7 Down = > L7Down; 
LIODown = > LIODOwn; 
R3 Down = > RSDOwn; 
R4 Down = > R4Down; 
R9 Down = > R9Down; 
RIO Down = > RIODOwn; 
T1 Down = > TIDown; 
T10 Down = > TIODOWn; 

ENOCASE.. 
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-File: NormalMouse.TIP last edit: 9-Mar'84 15:45:33 
OPTIONS Small; 

[DEF.SHIFT,{LeftShift Down | RightShift Down | Key47 Down | A12 Down)] 

SELECT TRIGGER FROM 

MOUSE = > SELECT ENABLE FROM 
Point Down = > COORDS, PointMotion; 
Adjust Down = > COORDS. AdjuStMotiOil; 

MouseMiddle Down = > COORDS, MouseMiddleMotion; 

ENDCASE,- 

Point Down = > SELECT (ENABLE FROM 

[SHIFT] = > TIME, COORDS. Shift, PolntDowri; 

ENDCASE = > TIME, COORDS. PointDowH; 
Point Up = > SELECT ENABLE FROM 

[SHIFT] = > TIME. COORDS. Shift. PolntUp; 

ENDCASE = > TIME, COORDS, PolntUp; 
Adjust Down = > SELECT ENABLE FROM 

[SHIFT] = > TIME, COORDS. Shift, AdjustDown; 

ENDCASE = > TIME. COORDS. AdjustDOWH; 
Adjust Up = > SELECT ENABLE FROM 
[SHIFT] = > TIME, COORDS, Shift, AdjustUp; 

ENDCASE = > TIME, COORDS, AdjustUp; 
MouseMiddle Down = > SELECT ENABLE FROM 

[SHIFT] = > TIME. COORDS, Shift, MoussMlddleDown; 
ENDCASE 3 > TIME, COORDS, MouseMlddleDown; 

MouseMiddle Up = > SELECT ENABLE FROM 

[SHIFT] = > TIME, COORDS, Shift, MouseMlddleUp; 

ENDCASE = > TIME. COORDS. MOUSeMlddlellp; 

ENTER = > Enter; 

EXIT = > Exit; 
ENDCASE.. 
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"File: NormalSideKeys.TIP last edit: 18-Mar-85 15:01:54 
—This file contains sidekey translations for the 8010. 

[DEF,ifShift,(SELECT ENABLE FROM 
LeftShift Down = > '1 
RightShift Down = > "1 ; 
Key47 Down = > "1 ; — JLevellV keyboard 
A12 Down = > "1 ; — JLevellV keyboard 

ENDCASE = > '2)1 



SELECT TRIGGER FROM 

— left function keys 

AGAIN Down => [lfShift,ShiftAgainOown,AgainOown]; 

AGAIN up => [lfShift,ShiftAgainUp,AgainUp]; 

DELETEDown => [lfShift,ShiftDeleteDown,De!eteDown]; 

DELETE Up = > [lfShift,ShiftDeleteUp,DeieteUpl; 

FIND Down => [lfShift,ShiftFindDown,FindDown]; 

FIND up => [IfShift.ShiftFindUp.FindUp]; 

COPY Down = > [lfShift,ShiftCopyDown,CopyDown]; 

COPY Up => [lfShift,ShiftCopyUp,CopyUp]; 

SAME Down => [lfShift,ShiftSameDown,SameDown]; 

SAME Up => [lfShift,ShiftSameUp,SameUp]; 

MOVE Down => [lfShift,ShiftMoveDown,MoveDown]; 

MOVE Up = > [lfShift,ShiftMoveUp,MoveUpl; 

OPEN Down = > [lfShift,ShiftOpenOown,OpenDown]; 

OPEN Up = > [lfShift,ShiftOpenUp,OpenUp]; 

PROPS Down = > [lfShift,ShiftPropsDown,PropsDown]; 

PROPS Up => [IfShift.ShiftPropsUp.PropsUp]; 

— right function keys 

NEXT Down => [IfShift.SkipOown.NextDown]; 

NEXT Up => [lfShift,SklpUp,NextUp]; 

UNDO Down => [lfShift,ShiftUndoDown,UndoDown]; 

UNDO Up => [IfShift.ShiftUndoUp.UndoUp]; 

MARGINS Down = > [lfShift,ShiftMarginsDown,MarginsDown]; 

MARGINS Up => [lfShift,ShiftMarginsUp,MarginsUp]; 

EXPANODown => [lfShift,DefineDown,ExpandDown]; 

EXPANDUp = > [IfShift.OefineUp.ExpandUp]; 



ENDCASE. 
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"F/Ve; NormalSideKeys.TIP last edit: 1 8- Mar-85 15:01:54 
—This file contains sidekey translations for the 6085. 

[DEF,lfShift,(SELECT ENABLE FROM 
LeftShift Down = > "1 ; 
RightShift Down = > ""1 ; 

LeftShiftAlt Down = > "1 ; -- JLeuellV keyboard 
RightShiftAtt Down = > "1 ; •- JLeuellV keyboard 
ENDCASE = > "'2)1 



SELECT TRIGGER FROM 

" left function keys 

AGAIN Down => [lfShift,ShiftAgainDown,AgainDown]; 

AGAIN up => [lfShift,ShiftAgainUp,AgainUp]; 

DELETE Down = > [lfShift,ShiftDeleteDown,DeleteDown]; 

DELETE Up = > [lfShift,ShiftDeleteUp,DeleteUpl; 

FIND Down => [lfShift,ShiftFmdDown,FindDown]; 

FIND Up => [lfShift,ShiftFindUp,FindUp]; 

COPY Down => [lfShift,ShiftCopyDown,CopyDownl; 

COPY Up => [lfShift,ShiftCopyUp,CopyUp]; 

SAME Down => [lfShift,ShiftSameDown,SameDown]; 

SAME Up = > [lfShlft,ShiftSameUp,SameUp]; 

MOVE Down = > [IfShift.ShiftMoveOown.MoveOown]; 

MOVEUp => IlfShift.ShiftMoveUp.MoveUpl; 

OPEN Down => (lfShift,ShiftOpenDown,OpenDown]; 

OPEN up => [IfShift.ShlftOpenUp.Openllpl; 

PROPS Down a> [lfShift,ShiftPropsDown,PropsDown]; 

PROPS Up => [lfShift,ShiftPropsUp,PropsUp]; 

UNDO Down => [lfShift,ShlftUndoDown,UndoDown]; 

UNDO Up = > [lfShift,ShiftUndoUp,UndoUp]; 

" beside space bar 

EXPAND Down s> [lfShift,DefineDown,ExpandDown]; 
EXPAND Up => [lfShift,DefineUp,ExpandUp]; 

-- right function keys 

NEXT Down => [lfShift,SkipDown,NextDown]; 
NEXT Up = > [lfShift,SkipUp,NextUp]; 

— calculator key pad 
KeypadZero Down => [lfShift,ShiftZeroDown,ZeroDownl; 
KeypadZeroUp => [IfShift.ShiftZeroUp.ZeroUp]; 
KeypadOne Down => llfShift,ShiftOneDown,OneDown]; 
KeypadOneUp => [lfShift,ShiftOneUp,OneUpI; 
KeypadTwo Down = > [lfShift,ShiftTwoDown,TwoDown]; 
KeypadTwoUp = > [IfShift.ShiftTwoUpJwoUpl; 
KeypadThree Down = > [lfShift,ShiftThreeDown,ThreeDown]; 
KeypadThree up => [IfShift.ShiftThreeUpJhreeUpl; 
KeypadFour Down => [IfShift.ShiftFourDown.FourDown]; 
KeypadFourUp = > (lfShift,ShiftFourUp,FourUpl; 
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KeypadFive Down = > [lfShift,ShiftFiveDown,FiveDown]; 
KeypadFive Up = > [lfShift,ShiftFiveUp,FiveUp]; 
KeypadSix Down => [lfShift,ShiftSixDown,SixDown]; 
KeypadSixup = > [lfShift,ShiftSixUp,SixUp]; 
KeypadSeven Down => [lfShift,ShiftSevenDown,SevenDownI; 
KeypadSeven Up = > [lfShift,ShiftSevenUp,SevenUp]; 
KeypadEight Down => (IfShift.ShiftEightDown.EightDownl; 
KeypadEight Up => [IfShift.ShiftEightUp.EightUp]; 
KeypadNine Down => [lfShift,ShiftNineDown,NineDown]; 
KeypadNineUp = > [ifShift,ShiftNineUp,NineUp]; 
KeypadAdd Down = > [lfShift,ShiftAcldOown,AclclDown]; 
KeypadAddup => [lfShift,ShiftAddUp,AddUp]; 

KeypadSubtract Down => [lfShift,ShiftSubtractDown,SubtractDown]; 
KeypadSubtract Up => [IfShift.ShiftSubtractUp.SybtractUp]; 
KeypadMuitiply Down => [lfShift,ShiftMultiplyOown,MultiplyOown]; 
KeypadMuitipiy Up => [lfShift,ShiftMultipiyUp,MuitiplyUp]; 
KeypadDivide Down => [lfShift,ShiftDivideOown,DivideDown]; 
KeypadDivide up => [lfShift,ShiftOivideUp,OivideUp]; 
Keypadciear Down => [lfShift,ShiftClearDown,ClearDown]; 
Keypadciear Up => [lfShift,ShiftCiearUp,ClearUp]; 
KeypadPeriod Down => [lfShift.ShiftPeriodDown,PeriodDown]; 
KeypadPeriod Up => [lfShift,ShiftPeriodUp,PeriodUp]; 
KeypadComma Down = > [lfShift,ShiftCommaDown,CommaDown]; 
KeypadComma Up => [lfShift,ShiftCommaUp,CommaUpl; 

ENDCASE... 
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-- f/7e; NormaiSoftKeys.TIP last edit: 23-Oct-84 20:21:33 
— This file contains softkeys translations for the 8010. 

[DEF,lfShift,(SELECT ENABLE FROM 
LeftShift Down = > "1 ; 
RightShift Down = > 1 ; 
Key47 Down = > '1 ; — JLevellV keyboard 
A12 Down = > 'I ; ■- JLevellV keyboard 

ENDCASE = > "2)1 



SELECT TRIGGER FROM 

— top function keys 

CENTER Down => [lfShift,ShiftCenterDown,CenterDown]; 

CENTER Up => [lfShift,ShiftCenterUp,CenterUp]; 

BOLD Down => [lfShift,UnboldDown,BoldDown]; 

BOLD Up => [lfShift,UnboidUp,BoldUp]; 

iTALicsDown = > [IfShift.ShiftltalicsDown.ltalicsDown]; 

ITALICS Up = > [lfShift,ShiftltalicsUp,ltalicsUp]; 

UNDERLINE Down => {lfShift,ShiftUnderlineDown,UnderlineDownl; 

UNDERLINE Up => (lfShift,ShiftUnderlineUp,UnderlineUp]; 

SUPERSCRIPT Down = > (lfShift,ShiftSuperscriptDown,SuperscriptDown]; 

SUPERSCRIPT Up => [lfShift,ShiftSuperscriptUp,SuperscriptUp]; 

SUBSCRIPT Down = > [If Shift,ShiftSubscriptDown,SubscriptDown]; 

SUBSCRIPT Up => [lfShift,ShiftSubscriptUp,SubscriptUp]; 

SMALLER Down => [lfShift,LargerDown,SmallerDown]; 

SMALLER Up = > [lfShift,LargerUp,SmallerUp]; 

DEFAULTS Down => [lfShift,ShiftDefaultsDown,DefaultsDown]; 

DEFAULTS Up = > [lfShift,ShiftDefaultsUp,DefaultsUp]; 

ENDCASE... 



All 
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-- f//e: NormalSoftKeys.TIP last edit: 23- Oct- 84 20:21:33 
- This file contains softkeys translations for the 6085. 

[OEF,lfShift,(SELECT ENABLE FROM 
LeftShift Down = > "1 
RightShift Down = > "1 ; 

LeftshiftAit Down = > " 1 ; — JLevellV keyboard 
RightshiftAit Down = > "1 ; JLevellV keyboard 

ENDCASE = > "2)1 



SELECT TRIGGER FROM 

— top function keys 

CENTER Down => [lfShift,ShiftCenterDown,CenterOown]; 
CENTER up => [lfShlft,ShiftCenterUp,CenterUpl; 
BOLD Down => [lfShift,UnbolclDown,BolclDown]; 
BOLD Up => [ifShift,UnbolciUp,BoldUp]; 
ITALICS Down = > [lfShift,ShiftltalicsDown,ltalicsDownl; 
ITALICS Up = > [lfShift,ShiftltalicsUp,ltalicsUp]; 
Case Down => [IfShift.ShiftCaseDown.CaseDown]; 
Case Up = > [lfShift,ShiftCaseUp,CaseUp]; 

UNDERLINE Down = > [lfShift,ShiftDbkUnderlineOown,DbkUnderiineDown]; 
UNDERLiNEUp => [lfShift,ShiftDbkUnderiineUp,DbkUnderiineUp]; 
Strikeout Down => [lfShift,ShiftStrikeoutDown,StrikeoutDown]; 
strikeout Up = > [lfShift,ShiftStrikeoutUp,StrikeoutUp]; 
SuperSubOown = > [lfShift,ShiftSuperSubOown,SuperSubDown]; 
SuperSubUp => [IfShift.ShiftSuperSubUp.SuperSubUp]; 
SMALLER Down => [lfShift,DbkLargerDown,DbkSmallerDown]; 
SMALLERUp => [lfShift,DbkLargerUp,DbkSmallerUp]; 
MARGINS Down => [IfShift.ShiftMarginsDown.MarginsOown]; 
MARGINS up => [ifShift,ShiftMarginsUp,MarginsUp1; 
FONT Down => [lfShift,ShiftFontDown,FontDown]; 
FONT Up => [lfShift.ShiftFontUp,FontUp]; 



ENDCASE... 
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A.2.2 Mouse Mode Tables 

The mouse mode tables refer to the set of tables that will be swapped in and out of the 
TIPStar watershed at the mouseActions placeholder, depending on the mode set by 
TiPStar.SetMode. Note: mode = normal will return NormalMouse.TIP to the watershed. 

-File: CopyModeMouse.TIP last edit: 28-May-85 18:12:42 

OPTIONS Small; 

SELECT TRIGGER FROM 

MOUSE = > SELECT ENABLE FROM 

Point Down = > COORDS, CopyModeMotion; 
Adjust Down = > COORDS, CopyModeMotion; 

ENDCASE: 

Point Down = > COORDS, CopyModeDown; 

Point Up s > COORDS, CopyModellp; 
Adjust Down = > COORDS, CopyModeOown; 
Adjust up s > COORDS, CopyModeUp; 

ENTER s > CopyModeEnter; 
EXIT s > CopyModeExit; 

ENDCASE.. 
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-File: MoveModeMouse.TIP /aste<//t; 28-May-85 
OPTIONS Smail: 
SELECT TRIGGER FROM 
MOUSE = > SELECT ENABLE FROM 

Point Down = > COORDS, MoveModeMotion; 

Adjust Down = > COORDS. MOveModeMOtiOH; 
ENDCASE; 

Point Down = > COORDS, MoveModeDown; 
Point Up = > COORDS. MoveModeUp; 
Adjust Down = > COORDS, MoveModeOowri; 
Adjust up = > COORDS, MoveModeUp; 

ENTER = > MoveModeEnter; 
EXIT = > MoveModeExit; 

ENDCASE.. 



16:37:23 
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-File: SameAsModeMouse.TIP last edit: 13-Jul-83 10:42:03 
OPTIONS Small; 
SELECT TRIGGER FROM 
MOUSE = > SELECT ENABLE FROM 

Point Down = > COORDS, SameAsModeMotion; 
Adjust Down = > COORDS, SameAsModeMotion; 

ENOCASE; 

Point Down = > COORDS, SameAsModeDown; 
Point Up = > COORDS, SameAsModeUp: 
Adjust Down 3 > COORDS, SameAsModeDown; 
Adjust up = > COORDS, SameAsModeUp; 

ENTER = > SameAsModeEnter; 
EXIT = > SameAsModeExit; 

ENDCASE... 



A System TIP Tables 

^^^^^ 



A.2.3 Miscellaneous Tables 



Any TiP.Tables created for ViewPoint should be added to this appendix by the responsible 
imple mentor. 
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A.3 Usage/Examples 

A.3.1 Using NormalSoftKeys.TIP when installing client softKeys 
— define the Atoms for my Notif yProc to use -- 

centerDown, boidDown, itaiicsOown, underlineDown, superscriptDown, 
subscriptDown, smallerDown, defaultsOown : Atom.ATOM «- Atom. null; 



Init: PROCEDURE = 
BEGIN 

" initialize my Atoms — 
centerDown <- Atom.MakeAtom["CenterDown"]; 
boidDown <-Atom.MakeAtom[ "BoldDown"L]; 
italicsDown <-Atom.MakeAtom("ltalicsDown"Ll: 
underlineDown <~Atom.MakeAtom["UnderlineDown"L]; 
superscriptDown 4- Atom. MakeAtom("SuperscnptDown"L]; 
subscriptDown *- Atom.MakeAtomt"SubscriptDown"L]; 
smallerDown <-Atom.MakeAtomrSmallerDown"L]; 
END; -Init 

— somewhere in the code - 
softKeyHandle <-SoftKeys.Push[ 
notifyProc: MyNotifyProc, 

labels: DESCRiPTOR(labels, SoftKeys. numberOf Keys] ]; 
MyNotifyProc: Tip.NotifyProc = 

BEGIN 

FOR input: TiP.Results «- results, input.next until input = nil do 

WITHZ: input SELECT FROM 

atom = > SELECT z.a from 
centerDown = > —Do something interesting--; 
boidDown => —Do something interesting--; 
itallcsDown = > —Do something interesting—; 
underlineDown => —Do something interesting— ; 
superscriptDown => -Do something interesting— ; 
subscriptDown = > —Do something interesting—; 
smallerDown = > —Do something interesting—; 
defaultsDown = > -Do something interesting—; 

ENDCASE 
ENDCASE 
ENDLOOP 

END; - MyNotifyProc 



MyNotifyProc will be attached to NormalSoftKeys.TIP by the SoftKeys implementation. Until 
this client does a SoftKeys.Remove, whenever the user presses one of the top row function 
keys MyNotifyProc will be called with the appropriate production from the 
NormatSoftKeys.TIP. 
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A.3.2 Attaching a Notify Proc to One of the Normal Tables 

If a client application wants to grab the use, for example, of all the side keys for some 
period of time, it can attach a notifyProc to the NormalSideKeys.TIP table by calling: 

old 4r- TiP.SetNotif yProcForTablelTiPStar.GetTable(sideKeys]. My NotifyProc); 
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A.4 Index of TIP Tables 



Item Page 

CopyModeMouse.TI^ 9 

MoveModeMouse.TIP 10 

NormalBackstop.TIP 3 

NormalKeyboard.TIP 4 

NormalMouse.TIP 6 

NormalSideKeys.TIP 7 

NormalSoftKeys.TIP 8 

SameAsModeMouse.TiP 11 

Other Miscellaneous tables 12 



A 
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References 

The following documents should be studied before or in conjunction with this manual: 

• Mesa Language Manual, - 610E00170. 

• XDE User Guide, - 610E!:00140. 

• Pilot Programmer's Manual, - 610E00160. 

• Srvices Programmer's Guide: Filing Programmer's Manual, - 610E00180. 

In addition, any other documentation accompanying a release of ViewPoint should be 
consulted before writing any programs. 
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Atoms 



C.l Overview 



Atoms (see Atom interface) are used in several places in ViewPoint. This appendix 
contains a list of the strings that represent them. 



C.1.1 Atoms as TIP Results in the System TIP Tables 

Most of the right-hand sides (TIP results) of the productions in the- system-provided TIP 
Tables (see Appendix A) contain atoms. 

AlODown 

ASDown 

A9Down 

AdjustDown 

AdjustMotion 

Adjust Up 

AgainDown 

Backspace 

BackWord 

BoldDown 

CenterDown 

CopyDown 

CopyModeDown 

CopyModeMotion 

Copy Mode Up 

CopyUp 

DlDown 

D2Down 

DefaultsDown 

DefmeDown 

Delete Down 

EnablePointlnvoke 

Enter 

Exit 

ExpandDown 
FindDown 



CI 
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Finish Finish 

FontDown 

FontUp 

HelpDown 

HelpUp 

Invoke 

ItalicsDown 

KeyboardDown 

KeyboardUp 

LlODown 

LI Down 

L4Down 

L7Down 

Larger Down 

LockDown 

Lockup 

Margins Down 

MouseMiddleDown 

MouseMiddleMotion 

MouseMiddleUp 

MoveDown 

MoveModeDown 

MoveModeMotion 

MoveModeUp 

MoveUp 

NewLine 

NewParagraph 

NextDown 

OpenDown 

ParaTabDown 

PointDown 

PointMotion 

PointUp 

PropsDown 

RlODown 

RSDown 

R4Down 

R9Down 

Same AsMode Down 

SameAsModeMotion 

SameAsModeUp 

Same Down 

Shift 

SkipDown 

SmallerDown 

Stop 

SubscriptDown 

SuperscriptDown 

TlODown 

TlDown 

TabDown 

Track 
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UnboldDown 
Under line Do wn. 
UndoDown 

C.1.2 Passed as the **Atom" Parameter to a Containee.GenericProc 

These atoms may be passed to a Containee.GenericProc as the atom parameter, indicating 
what operation the GenericProc should perform: 

Can YouTakeSe lection 

Open 

Props 

TakeSelection 
TakeSeleotionCopy 

C.1.3 Event Atoms 

Events are identified by atoms (see the Event interface). The following events are 
explained in further detail in the chapter indicated. 



Event 

AttemptingStar Logoff 

BlackKeysChange 

DesktopWindowAvailable 

Newlcbn 

StarLogoff 

Star Logon 



Chapter where discussed 

Star Desktop 

BlackKeys 

StarDesktop 

Star Desktop 

StarDesktop 

StarDesktop 



C.1.4 AtomicProfile Atoms 



AtomicProfile is used to sav^e various values globally. Values are saved with the following 
atoms. 

FullUserName-Fully qualified user's name as entered by the user at logon. 
UserPassword-Lrser's password as entered by the user at logon. 



C.1.5 Other 



The Atom interface allows any value to be associated with any pair of atoms (see 
Atom.GetProp, Atom. Pair, etc.). 



Atom 

CurrentUser 



Property atom 
IdentityHandle 



Value 

identity. Handle for the currently logged 
on user. This is created at logon if the 
user enters a password; it can be used to 
access any Network Service. 
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Listing of Public Symbols 



This appendix lists all public items from the public interfaces, i. e. the files in 
XStringPublic.dfand BWSPublic.df. 

Atom AtomicProfile Attention BlackKeys Containee ContaineeExtra ContainerCache 
ContainerCacheExtra ContainerSource ContainerWindow Context Cursor Display 
DisplayExtra Event FileContainerShell FileContainerSource FUeContainerSourceExtra 
FormWindow FormWindowMessageParse IdleControl KeyboardKey KeyboardWindow 
LevellVKeys MenuData MessageWindow PopupMenu PropertySheet Selection 
SimpleTextDisplay SimpleTextEdit SimpleTextFont SoftKeys StarDesktop 
StarWindowShell TIP TIPStar Undo Window XChar XCharSetO XCharSet164 XCharSet356 
XCharSet357 XCharSet41 XCharSet42 XCharSet43 XCharSet44 XCharSet45 XCharSet46 
XCharSet47 XCharSets XComSoftMessage XForma t XLReal XMessage XString 
XStringExtra XStringX XTime XToken 

Abs: -XLReal-' procedure [Number] returns [Number]; 
accuracy: --Xi./?ea/-- NATURAL = 13; 

Acquire: --Context-- procedure [type: Type, window: window. Handle] 
RETURNS [Data]; 

Action: --Conta/nerSource-- type = {destroy, reList, sleep, walceup}; 
Action: --Se/ect/on-- TYPE = machine dependent{ 

clear, mark, unmark, delete, clearlfHaslnsert, save, restore, firstFree, 

last(255)}; 

actionToWindow: -TIP- packed array KeyName of boolean; 
ActOn: -ContainerSource - ActOnProc; 
ActOn: -Selection- procedure [action: Action]; 
ActOnProc; -ContainerSource- type = procedure [ 

source: Handle, action: Action]; 
ActOnProc: --Se/ect/on-- type = procedure [data: ManagerData, action: Action] 

returns [cleared: boolean ^ false]; 
Add: -XLReal- procedure [a: Number, b: Number] returns [Number]; 
AddClientDefinedCharacter: -SimpleTextFont- procedure [ 

width: cardinal, height: cardinal, bitsPerLine: cardinal, bits: long pointer, 

offset Into Bits: cardinal «-0] returns [xstrmg. Character]; 
AddData: --Conta/nerCac/7e-- type = record [ 

clientData: long pointer, 

clientDataCount: cardinal, 

clientStrings; long Descriptor for array cardinal of xstnng.ReaderBody]; 
AddDependencies: -Event - procedure [ 

agent: AgentProcedure, myData: long pointer, 
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Add: -PrototypeExtra-- procedure [ 

file: NSFile. Handle, version: Prototype. Version, 

subtype: Prototype.Subtype " 0, session: NSFile.Session ^ LOOPHOLE[0]]; 
Add: --XLReal - procedure [a: Number, b: Number] returns [Number]; 
AddClientDefinedCharacter: -SimpleTextFont- procedure [ 

width: cardinal, height: cardinal, bitsPerLine: cardinal, bits: long pointer, 

offsetlntoBits: cardinal " 0] returns [XString. Character]; 
Add Data : "Conta/nerCache-- type = record [ 

clientData: long pointer, 

clientDataCount: cardinal, 

clientStrings: long descriptor for array cardinal of XString. ReaderBody]; 
AddDependencies: --Event- procedure [ 

agent: AgentProcedure, myData: long pointer, 

events: long descriptor for array cardinal of EventType, 

remove: FreeDataProcedure " nil] returns [dependency: Dependency]; 
AddDependency: -Event- procedure [ 

agent: AgentProcedure, myData: long pointer, event: EventType, 

remove: FreeDataProcedure ^ nil] returns [dependency: Dependency]; 
Addltem: -MenuData- procedure [menu: MenuHandle, new: ItemHandle]; 
AddMenultem: --Attent/on-- procedure [item: MenuData. ItemHandle]; 
AddPopupMenu: -StarWindowShell - procedure [ 

sws: Handle, menu: MenuData. MenuHandle]; 
AddReferenceToDesktop: -StarDesktop- procedure [ 

reference: NSFile.Reference, place: Window. Place " nextPlace]; 
AddToSystemKeyboards: --/CeyboardfCey - procedure [keyboard: 
BlackKeys. Keyboard]; 

AdjustProc: "StarW/nc/ovvS/ie//-- type = procedure [ 

sws: Handle, box: Window Box, when: When]; 
AgentProcedure: --Event - TYPE = procedure [ 

event: EventType, eventData: long pointer, myData: long pointer] 

RETURNS [remove: boolean " false, veto: boolean false]; 
AllocateAndlnsert: -A/fessage\/V/nc/ow~ procedure [ 

parent: Window.Handle, place: Window. Place " LOOPHOLE[0], 

dims: Window.Dims " LOOPHOLE[23417B], zone: uncounted zone " LOOPHOLE[0], 

lines: cardinal ' 10] returns [Window.Handle]; 
AliocateCache: -ContainerCache- procedure returns [Handle]; 
AliocateMessages: -XMessage- procedure [ 

applicationName: long string, maxMessages: cardinal, clientData: ClientData, 

proc: DestroyMsgsProc] returns [h: Handle]; 
Alphabetic: -XToken- FilterProcType; 
AlphaNumeric: -XToken- FilterProcType; 
Append: -XTime- procedure [ 

w: XString. Writer, time: System. GreenwichMeanTime ^ defaultTime, 

template: XString. Reader ' dateAndTime, Itp: LTP " useSystem]; 
AppendChar: -XString- procedure [ 

to: Writer, c: Character, extra: cardinal " 0]; 
AppendExtensionlf Needed: -XString- procedure [to: Writer, extension: Reader] 

returns [didAppend: boolean]; 
Appendltem: -ContainerCache- procedure [cache: Handle, addData: AddData] 

returns [handle: ItemHandle]; 
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Appendltem: --Form Window- procedure [ 

window: Window. Handle, item: ItemKey, line: Line, preMargin: cardinal " 0, 

tabStop: cardinal ^ nextTabStop, repaint: boolean " true]; 
AppendLine: -FormWindow- procedure [ 

window: Window.Handle, spaceAboveLine: cardinal ' 0] returns [line: Line]; 
AppendReader: -XString- procedure [ 

to: Writer, from: Reader, fromEndContext: Context " unknownContext, 

extra: cardinal " 0]; 
AppendStream: -XString- procedure [ 

to: Writer, from: Stream, Handle, nBytes: cardinal, 

fromContext: Context ' vanillaContext, extra: cardinal ' 0] 

returns [bytesTransf erred: cardinal]; 
AppendSTRING: -XString- procedure [ 

to: Writer, from: long string, homogeneous: boolean " false, 

extra: cardinal " 0]; 
ArabicFirstRightToLeftCharCode: -XChar- Environment.Byte = 48; 
Arc: -Display - procedure [ 

window: Handle, place: Window. Place, radius; integer, startSector: cardinal, 

stopSector: cardinal, start: Window. Place, stop: Window.Place, 

lineStyle: LineStyle " nil, bounds: Window. BoxHandle ' nil]; 
ArcCos: -XLReal- procedure [x: Number] returns [radians: Number]; 
ArcSin: -XLReal- procedure [x: Number] returns [radians: Number]; 
ArcTan: -XLReal- procedure [x: Number] returns [radians: Number]; 
ArrayHandle: -MenuData- type = long descriptor for array cardinal of 

ItemHandle; 

ArrowFlavor: -StarWindowShell- type = {pageFwd, pageBwd, forward, backward}; 
ArrowScrollActi on : --StarW/ncyowS/7e//- type = {start, go, stop}; 
ArrowScrol I Proc : -StarMZ/ndowS/ie//-- type = procedure [ 

sws: Handle, vertical: boolean, flavor: ArrowFlavor, 

arrowScrol I Action: ArrowScrollAction ' go]; 
atom: -Atom- type [1]; 
atom: - r/P- TYPE = Atom. atom; 
attemptingLogoff : -StarDesktop- Atom. atom; 
AttentionProc: -- r/P - TYPE = procedure [window: Window.Handle]; 
AttributeFormatProc: -FileContainerSource- type = procedure [ 

containeelmpi: Containee. Implementation, containeeData: Containee.DataHandle, 

attr: NSFile.Attribute, displayString: XString.Writer]; 
BackScanClosure: -XString - type = record [ 

proc: BackScanProc, env: long pointer]; 
BackScanProc: --XStnng-- type = procedure [ 

beforePos: cardinal, env: long pointer] 

returns [pos: CARDINAL, context: Context]; 
backStoplnputFocus: -TIP- readonly Window.Handle; 
beforeltemZero: --Conta/nerSource-- Itemlndex = 177776B; 
beforeLogonSession: -Catalog- NSFile. Session; 
BeginFill: -ContainerCache - procedure [ 

cache: Handle, fillProc: FillProc, clients: long pointer, 

fork: boolean " true]; 
Bit: -/.eveZ/VfCeyS" TYPE = KeyStations.Bit; 
BitAddress: --D/sp/ay-- TYPE = BitBlt.BitAddress; 
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BitAddressFromPlace: -D/sp/ay-- procedure [ 

base: BitAddress, x: natural, y: natural, raster: cardinal] 

RETURNS [BitAddress]; 
BitBltFlags: --D/sp/ay-- TYPE = BitBlt.BitBltFlags; 
bitFlags: -Display- BitBltFlags; 
Bitmap: -Display- procedure [ 

window: Handle, box; Window Box, address: BitAddress, 

bitmapBitWidth: cardinal, flags: BitBltFlags " paintFlags, 

bounds: Window. BoxHandle " nil]; 
Bitmap: -FormWindow- type = record [ 

height: cardinal, 

width: cardinal, 

bitsPerLine: cardinal, 

bits: Environment.BitAddress]; 
BitmapPlace: -Window- procedure [window: Handle, place: Place " LOOPHOLE[0]] 

RETURNS [Place]; 

BitmapPlaceToWindowAndPlace: -Window- procedure [bitmapPlace: Place] 

RETURNS [window: Handle, place: Place]; 
Bits: -XLReal - type = array [0..31 of cardinal; 
Black: -Display - procedure [ 

window: Handle, box: Window. Box, bounds: Window. BoxHandle " nil]; 
BiackParallelogram: -Display- procedure [ 

window: Handle, p: Parallelogram, dstFunc: DstFunc " null, 

bounds: Window. BoxHandle * nil]; 
Blanks: -XFormat- procedure [h: Handle * nil, n: cardinal " 1]; 
Block: -XFormat- procedure [h: Handle - nil, block: Environment.Block]; 
Block: -XString- procedure [r: Reader] 

RETURNS [block: Environment.Block, context: Context]; 
BodyEnumProc: -StarWindowShell type = procedure [victim: Window. Handle] 

RETURNS [stop: BOOLEAN " FALSE], 

Boolean: -XToken- procedure [h: Handle, signalOnError: boolean " true] 

RETURNS [true: boolean]; 
BooleanChangeProc: -FormW/ndow- type = procedure [ 

window: Window. Handle, item; ItemKey, calledBecauseOf: ChangeReason, 
newValue: boolean]; 
BooleanFalseDefault: -PropertyS/ieet- type = boolean ' false; 
BooleanltemLabel; -FormWindow- type = record [ 
var: select type: BooleanltemLabelType from 
string = > [string: XString. ReaderBody], 
bitmap = > [bitmap: Bitmap], 
endcase]; 

BooleanltemLabelType: -FormW/nc/ow- TYPE = {string, bitmap}; 
Box: -KeyboardWindow - type = record [ 

place: Window. Place, width: integer, height: integer]; 
Box: -W/ncyow- type = record [place: Place, dims: Dims]; 
BoxEnumProc: -Window- type = procedure [Handle, Box]; 
BoxesAreDlsjoint: -Window- procedure [a: Box, b: Box] returns [boolean]; 
boxFlags: -Display- BitBltFlags; 
BoxHandle: -Window- type = long pointer to Box; 
Brackets: -XToken- QuoteProcType; 

BreakCharOption: -XStr/ng- type = {ignore, appendToFront, leaveOnRest}; 
BreakTable: -XStr/ng- type = long pointer to BreakTableObject; 
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BreakTableObject: - XString- type = record! 
otherSets: StopOrNot ' stop, 
set: Environment. Byte " 0, 

codes: packed array [0..255] of StopOrNot " ALL[not]]; 
Brick: --Display-- type = long descriptor for array cardinal of cardinal; 
BufferProc: SimpleTextDisplay- type = procedure [ 

result: Result, string: XString. Reader, address: Environment. BitAddress, 

dims: Window. Dims, bitsPerLine: cardinal] returns [continue: boolean]; 
Byte: --XStr/ng-- type = Environment.Byte; 
ByteLength: -XString- procedure [r: Reader] returns [cardinal]; 
Bytes: -XString- type = long pointer to ByteSequence; 
ByteSequence: "XStr/ng-- TYPE - record [ 

packed sequence computed cardinal of Byte]; 
CacheFillStatus: -ContainerCache- type = { 

no, inProgress, inProgressPendingAbort, inProgressPendingJoin, yes, 

yesWith Error, spare}; 
Call Back : "f/P-- procedure [ 

window: Window. Handle, table: Table, notify: CallBackNotifyProc]; 
CallBackNotifyProc: -TIP-type = procedure [ 

window: Window. Handle, results: Results] returns (done: boolean]; 
CancelPeriodicNotify: -TIP - procedure [PeriodicNotify] 

returns [null: PeriodicNotify]; 
CanYouConvert: -Se/ect/on-- procedure ( 

target: Target, enumeration: boolean ' false] returns [yes: boolean]; 
CanYouTake: -ContainerSource- CanYouTakeProc; 
CanYouTakeProc: -ContainerSource- type = procedure [ 

source: Handle, selection: Selection. ConvertProc " nil] 

returns [yes: boolean]; 
caretRate: -TIP - Process. Ticks; 

CatalogProc: --Cata/og-- type = procedure [catalogType: NSFile.Type] 

returns [continue: boolean " true]; 
Changelnfo: -ContainerSource- type = record [ 

var: select changeType: ChangeType from 
replace = > [item: Itemlndex], 

insert = > [Insertlnfo: long descriptor for array cardinal of Editlnfo], 
delete = > [deletelnfo: Editlnfo], 

all - > NULL, 

noChanges = > null, 
endcase]; 

ChangeProc: --Conta/nee-- type = procedure [ 

changeProcData: long pointer, data: DataHandle " nil, 

changedAttributes: NSFile. Selections " [xxxx], noChanges; boolean " false] 
ChangeProc: -ContainerSource- type = procedure [ 

changeProcData: long pointer, changelnfo: Changelnfo]; 
ChangeReason: --Form W/ncyow - type = {user, client, restore}; 
ChangeScope: ~F//eConta/nerSource-- procedure [ 

source: ContainerSource. Handle, newScope: NSFile.Scope]; 
ChangeSizeProc: ~S/mp/erextEd/t- TYPE = procedure [ 

f: Field, oldHeight: integer, newHeight: integer, repaint: boolean]; 
ChangeType: -ContainerSource - type = { 

replace, insert, delete, all, noChanges}; 
Char: -XFormat- procedure [h: Handle " nil, char: XString. Character]; 
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Character: -XChar - type = word; 

Character: --XStr/ng-- TYPE = XChar. Character; 

CharacterLength: -XString- procedure [r: Reader] returns [cardinal]; 

CharRep: -XChar- type = machine dependent record [ 

set(0:0..7): Environment.Byte, code(0:8..15): Environment.Byte]; 
CharTranslator: -TIP - type = record [proc: KeyToCharProc, data: long pointer]; 
ChoiceChangeProc: -FormWindow - type = procedure [ 

window: Window. Handle, item: ItemKey, calledBecauseOf: ChangeReason, 

oldValue: Choicelndex, newValue: Choicelndex]; 
ChoiceHintsProc: -FormWindow- type = procedure [ 

window: Window.Handle, item: ItemKey] 

RETURNS [ 

hints: LONG descriptor for ARRAY CARDINAL OF Choicelndex, 

freeHints: FreeChoiceHintsProc]; 
Choicelndex: "FormW/ndow-- TYPE = cardinal [0. .377778]; 
Choiceltem: --Form W/ndow-- type = record [ 
var: select type: ChoiceltemType from 

string = > [choiceNumber: Choicelndex, string: XString. ReaderBody], 

bitmap = > [choiceNumber: Choicelndex, bitmap: Bitmap], 

wraplndicator = > null, 

endcase]; 

Choiceltems: -FormWindow- type = long descriptor for array Choicelndex of 
Choiceltem; 

ChoiceltemType: --Form W/ndow- type = {string, bitmap, wraplndicator}; 

Circle: -D/sp/ay- procedure [ 

window: Handle, place: Window. Place, radius: integer, 
lineStyle: LineStyle " nil, bounds: Window. BoxHandle " nil]; 

Clarity: ~W/ndow~ type = {isClear, isDirty}; 

Clear: -Attention- procedure; 

Clear: -MessageWindow- procedure [window: Window.Handle]; 
Clear: ~Se/ect/on~ procedure [unmark: boolean * true]; 
ClearlnputFocusOnMatch: -TIP- procedure [Window.Handle]; 
ClearManager: ~r/P~ procedure; 
ClearOnMatch: -Selection- procedure [ 

pointer: ManagerData, unmark: boolean ' true]; 
ClearSticky: -Attention- procedure; 
ClearWriter: -XStr/ng~ procedure [w: Writer]; 
clickTimeout: -TIP - System. Pulses; 
CI ientData : -XFormat- type = long pointer; 
ClientData: -X/Wessage- type = long pointer; 

clientDirectoryWords: -BWSAttributeTypes- NSFile.ExtendedAttributeType = 
10373B; 

clientPileWords: -BWSAttributeTypes- NSFile.ExtendedAttributeType = 10372B; 

Clients: -ContainerCache- procedure [cache: Handle] 
returns [clients: long pointer]; 

clientSize: BWSAttributeTypes NSFile.ExtendedAttributeType = 10375B; 

clientStatus: -SWSAttr/buterypes- NSFile.ExtendedAttributeType = 10374B; 

Code: -XChar- procedure [c: Character] returns [code: Environment.Byte]; 

CodesO: -XC/iarSetO- type = machine dependent{ 

null, tab(9), lineFeed, formFeed(1 2), newLine, esc(27), space(32), 
exclamationPoint, neutral DoubleQuote, numberSign, currency, percentSign, 
ampersand, apostrophe, openParenthesis, closeParenthesis, asterisk, plus. 
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comma, minus, period, slash, digitO, digiti, digit2, digit3, digit4, digits, 
digits, digit?, digits, digit9, colon, semicolon, lessThan, equals, 
greaterThan, questionMark, commercialAt, upperA, upperB, upperC, upperD, 
upperE, upperF, upperG, upperH, upper!, upperJ, upperK, upperL, upperM, 
upperN, upperO, upperP, upperQ, upperR, upperS, upperT, upperU, upperV, 
upperW, upperX, upperY, upperZ, openBracket, backslash, closeBracket, 
circumflex, lowBar, grave, lowerA, lowerB, lowerC, lowerD, lowerE, lowerF, 
lowerG, lowerH, lowerl, lowerJ, lowerK, lowerL, lowerM, lowerN, lowerO, 
lowerP, lowerQ, lowerR, lowerS, lowerT, lowerU, lowerV, lowerW, lowerX, 
lowerY, lowerZ, openBrace, verticalBar, closeBrace, tilde, 
invertedExelamation(161), cent, poundSterling, dollar, yen, section(167), 
leftSingleQuote(169), leftDoubleQuote, leftDoubleGuillemet, leftArrow, 
upArrow, rightArrow, downArrow, degree, piusOrMinus, superscript2, 
superscripts, multiply, micro, paragraph, centered Dot, divide, 
rightSingleQuote, rightDoubleQuote, rightDoubleGuiliemet, oneQuarter, oneHalf, 
threeQuarters, invertedQuestionMark, graveAccent(193), acuteAccent, 
circumflexAccent, tildeAccent, macronAccent, breveAccent, overDotAccent, 
dieresisAccent, overRingAccent(202), cedilla, underline, doubleAcuteAccent, 
ogonek, hachekAccent, horizontalBar, superscript!, registered, copyright, 
trademark, musicNote, oneEighth(220), threeEighths, fiveEighths, sevenEighths, 
ohmSign, upperAEdigraph, upperDstroke, feminineSpanishOrdinal, upperHstroke, 
upperlJdiagraph(230), upperLdot, upperLstroke, upperOslash, upperOEdiagraph, 
masculineSpanishOrdinal, upperThorn, upperTstroke, upperEng, lowerNapostrophe, 
lowerKgreenlandic, lowerAEdigraph, lowerDstroke, lowerEth, lowerHstroke, 
lowerldotless, low^erlJdiagraph, lowerLdot, lowerLstroke, lowerOslash, 
lowerOEdiagraph, lowerSzed, lowerThorn, lowerTstroke, lowerEng, escape}; 

Codes! 64: --XC/)arSet/64- TYPE = machine depei\ident{ 

kabu(33), maruA, marul, maruU, maruE, maruO, maruRo, maruHa, maruNi, maruHo, 
maruHe, maruTo, maruTi, maruRi, maruNu, reserved(255)}; 

Codes3S6: -X€harSet356- TYPE - machine dependent{ 

thick5pace(33), fourEmSpace, hairSpace, punctuationSpace, decimalPoint(46), 
absoluteValue(!24), similarTo(!26), escape(255)}; 

Codes3 57 : --XC/jarSetJ57- type = machine dependent{ 

nonBreakingSpace(33), nonBreakingHyphen, discretionaryHyphen, enDash, emDash, 
figureDash, neutralQuote, loweredLeftDoubleQuote, germanRightDoubleQuote, 
guillemetLeftQuote, guillemetRightQuote, enQuad, emQuad, figureSpace, 
thinSpace, dagger, doubleDagger, bra, ket, rightPointinglndex, 
leftPointinglndex, leftPerp, rightPerp, keft2Perp, right2Perp, 
leftWhiteLenticularBracket, rightWhiteLenticularBracket, nwArrow, seArrow, 
neArrow, swArrow, careOf, perThousand, muchLessThan, muchGreaterThan, 
notLessThan, notGreaterThan, divides, doesNotDivide, parallel, notParallel, 
isAMemberOf, isNotAMemberOf, suchThat, doubleBackArrow, doubleDoubleArrow, 
doubleRightArrow, reversibleReaction2, reversibleReaction!, doubleArrow, 
curlyArrow, contains!, containedin!, intersection, union, containsOrEquals, 
containedlnOrEquals, contains2, containedln2, neitherConatainsNorlsEqualTo, 
neitherContainedlnNorlsEqualTo, doesNotContain, isNotContainedIn, 
checketBallotBox, nullSet, abstractPlus, abstractMinus, abstractTimes, 
abstractDivide, centeredBullet, centeredRing, plancksConstant, litre, not, 
borkenVerticalBar, angle, sphericalAngle, identifier, because, perpendicular, 
isProportionalTo, equivalent, equalByDefinition, questionedEquality, integral, 
contourlntegral, approximatelyEqual ! , isomorphic, approximatelyEqual2, 
summation, product, root, minusOrPlus, shade, cruzeiro(!6!), florin, francs. 
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pesetas, europeanCurrency, milreis, genericlnfinity, number, take, tel, yogh, j 

com pi ex Number, naturalNumber, realNumber, integer, leftCeiling, rightCeiling, 

leftFloor, rightFloor, therExists, forAII, and, or, qed, nabia, 

partial Derivative, ocrHook, ocrFork, ocrChair, alternatingCurrent, 

doubleLowBar, arc, romanNumerall, romanNumeralll, romanNumerallll, 

romanNumerallV, romanNumeralV, romanNumeralVI, romanNumeralVII, 

romanNumeralVIII, romanNumerallX, romanNumeralX, spades, hearts, diamonds, 

clubs, checkMark, xMark, circled 1, circled2, circled3, circled4, circledS, 

circled6, circled?, circledS, circled9, circled 10, circled RightArrow, 

circledRightThenDownArrow, circled DownThenLeftArrow, peaceSymbol, smileFace, 

poison, thickVerticalLine, thickHorizontalLine, thicklntersectingLines, 

thinVerticalLine, thinHorizontalLine, thinlntersectingLines, sun, 

firstQuarterMoon, thirdQuarterMood, mercury, jupiter, saturn, uranus, neptune, 

pluto, aquarius, pisces, aries, taurus, gemini, cancer, leo, virgo, libra, 

scorpius, Sagittarius, Capricorn, telephone, oneThird, twoThirds, escape}; 

Codes360: -XCharSet360- type = machine dependent{ 

ligatureFF(33), ligatureFFI, ligatureFFL, ligatureFI, ligatureFL, ligatureFT, 

sigmaFinal(126), verticalTabGraphic(184), tabGraphic, lineFeedGraphic, 

formFeedGraphic, carriageReturnGraphic, newLineGraphic, available276B, 

available277B, available300B, available301 B, pageFormatGraphic, 

startOfDocumentGraphic, stopGraphic, available305B, available306B, 

available307B, available310B, available31 1 B, blackRectGraphic, 

checkerBoardGraphic, ibmDup, available31 5B, ibmFm, paraTabGraphic(217), 

available332B, available333B, available334B, newParagraphGraphic, ^g—i^ 

available336B, available337B, available340B, boxMT, boxNQT, boxEllipsis, | 1 

boxRange, boxUpperX, boxUpperA, boxdigit9, boxUpperZ, boxAsterisk, 

available352B, available353B, boxPlus, boxMinus, boxPeriod, boxComma, 

fieldFormatGreek(246), fieldFormatRussian, fieldFormatHiragana, 

fieldFormatKatakana, fieldFormatKanji, fieldFormatJapanese, spaceGraphicdot, 

spaceGraphicb, escape(255)}; 

Codes361 : --XC/7arSet357-- type = machine dependent{ 

upperAgrave(33), upperAacute, upperAcircumflex, upperAtilde, upperAmacron, 

upperAbrev, upperAumlaut, upperAring, upperAogonek, upperCacute, 

upperCcircumflex, upperChighDot, upperCcedilla, upperChachek, upperDhachek, 

upperEgrave, upperEacute, upperEcircumflex, upperEmacron, upperEhighDot, 

upperEumlaut, upperEogonek, upperEhachek, upperGcircumflex(57), upperGbrev, 

upperGhighDot, upperGcedilla, upperHcircumflex, upperlgrave, upperlacute, 

upperlcircumflex, upperltilde, upperlmacron, upperlhighDot, upperlumlaut, 

upperlogonek, upperJcircumflex, upperKcedilla, upperlacute, upperLcedilla, 

upperLhachek, upperNacute, upperNtilde, upperNcedilla, upperNhachek, 

upperOgrave, upperOacute, upperOcircumflex, upperOtilde, upperOmacron, 

upperOumlaut, upperODoubleAcute, upperRacute, upperRogonek, upperRhachek, 

upperSacute, upperScircumflex, upperScedilla, upperShachek, upperTcedilla, 

upperThachek, upperUgrave, upperUacute, upperUcircumflex, upperUtilde, 

upperUmacron, upperUbrev, upperUumlaut, upperUring, upperUDoubleAcute, 

upperUogonek, upperWcircumflex, upperYgrave, upperYacute, upperYcircumflex, 

upperYumlaut, upperZacute, upperZhighDot, upperZhachek, lowerAgrave(161), 

lowerAacute, lowerAcircumflex, lowerAtilde, lowerAmacron, lowerAbrev, jgp^ 

lowerAumlaut, lowerAring, lowerAogonek, lowerCacute, lowerCcircumflex, | 

lowerChighDot, lowerCcedilla, lowerChachek, lowerDhachek, lowerEgrave, 

lowerEacute, lowerEcircumflex, lowerEmacron, lowerEhighDot, lowerEumlaut, 

lowerEogonek, lowerEhachek, lowerGacute, lowerGcircumflex, lowerGbrev, 
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lowerGhighDot, lowerHcircumflex(189), lowerlgrave, lowerlacute, 
lowerlcircumflex, lowerrtilde, lowerlmacron, lowerlumlaut(196), lowerlogonek, 
lowerJcircumflex, lowerKcedilla, lowerLacute, lowerLcedilla, lowerLhachek, 
lowerNacute, lowerNtilde, lowerNcedilla, lowerNhachek, lowerOgrave, 
lowerOacute, lowerOcircumflex, lowerOtilde, lowerOmacron, lowerOumlaut, 
lowerODoubleAcute, lowerRacute, lowerRogonek, lowerRhachek, lowerSacute, 
lowerScircumflex, lowerScedilla, lowerShachek, lowerTcedilla, lowerThachek, 
lowerUgrave, lowerUacute, lowerUcircumflex, lowerUtilde, lowerUmacron, 
lowerUbrev, lowerUumlaut, lowerUring, lowerUDoubleAcute, lowerUogonek, 
lowerWcircumflex, lowerYgrave, lowerYacute, lowerYcircumflex, lowerYumlaut, 
lowerZacute, lowerZhighDot, lowerZhachek, escape(255)}; 

Codes41 : --XC/7arSef4/-- TYPE = machine dependent{ 

kanjiSpace(33), japaneseComma, japanesePeriod, dakuonMark(43), handakuonMark, 
repeatHiragana(51), repeatHiraganaWithDakuon, repeatKatakana, 
repeatKatakanaWithDakuon, reduplicate, reduplicateAboveltem, repeatKanji, 
shime, kanjiZero, longVowelBar, hyphen(62), parallelSign(66), 
threeDotLeader(68), twoDotLeader, leftBrokenBracket(76), rightBrokenBracket, 
leftJapaneseQuote(86), rightJapaneseQuote, leftJapaneseDoubleQuote, 
rightJapaneseDoubleQuote, leftBlackLenticularBracket, 
HghtBlackLenticularBracket, notEqual(98), lessThanOrEqualTo(IOI), 
greaterThanOrEqualTo, infinity, therefore, male, female, minutes(108), 
seconds, degreesCelsius, whiteStar(121), blackStar, whiteCircle, blackCircle, 
bullsEye, whiteDiamond, escape(255)}; 

Codes42: -XC/7arSet42-- TYPE = machine dependent{ 

blackDiamond(33), whiteSquare, blackSquare, whiteUpTriangle, blackUpTriangle, 
whiteDownTriangle, blackDownTriangle, jisKome, jisPostOffice, e5cape(255)}; 

Codes43: --XC/7arSet43- TYPE = machine dependent{ 

musicalFlat(172), soundRecordingCopyright(174), ayn(176), alifHamzah, 
lowerLeftQuote, musicalSharp(188), mjagkijZnak, tverdyjZnak, risingTone(192), 
umlaut(201), highCommaOffCentre(203), highlnvertedComma, horn(206), 
hookToTheLeft(210), circleBelow(212), halfCircleBelow, dotBelow, 
doubleDotBelow, doubleUnderline(217), africanVerticalBar, circumflexUndermark, 
leftHalfOfLigature(221), rightHalfOfLigature, rightHalfOfDoubleTilda, 
escape(255)}; 

Codes44: --XC/iarSet44-- TYPE = machine dependent{ 

hirSmallA(33), hirA, hirSmalll, hirl, hirSmallU, hirU, hirSmallE, hirE, 
hirSmallO, hirO, hirKa, hirGa, hirKi, hirGi, hirKu, hirGu, hirKe, hirGe, 
hirKo, hirGo, hirSa, hirZa, hirSi, hirJi, hirSu, hirZu, hirSe, hirZe, hirSo, 
hirZo, hirTa, hirDa, hirTi, hirDi, hirSmalITu, hirTu, hirDu, hirTe, hirDe, 
hirTo, hirDo, hirNa, hirNi, hirNu, hirNe, hirNo, hirHa, hirBa, hirPa, hirHi, 
hirBi, hirPi, hirHu, hirBu, hirPu, hirHe, hirBe, hirPe, hirHo, hirBo, hirPo, 
hirMa, hirMi, hirMu, hirMe, hirMo, hirSmallYa, hirYa, hirSmallYu, hirYu, 
hirSmallYo, hirYo, hirRa, hirRi, hirRu, hirRe, hirRo, hirSmallWa, hirWa, 
hirWi, hirWe, hirWo, hirN, escape(255)}; 

Codes45: -XCharSet45-- type = machine dependent{ 

katSmallA(33), katA, katSmalll, kati, katSmallU, katU, katSmallE, katE, 
katSmallO, katO, katKa, katGa, katKi, katGi, katKu, katGu, katKe, katGe, 
katKo, katGo, katSa, katZa, katSi, katJi, katSu, katZu, katSe, katZe, katSo, 
katZo, katTa, katDa, katTi, katDi, katSmalITu, katTu, katDu, katTe, katDe, 
katTo, katDo, katNa, katNi, katNu, katNe, katNo, katHa, katBa, katPa, katHi, 
katBi, katPi, katHu, katBu, katPu, katHe, katSe, katPe. katHo, katBo, katPo, 
katMa, katMi, katMu, katMe, katMo, katSmallYa, katYa, katSmallYu, katYu, 
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katSmallYo, katYo, katRa, katRi, katRu, katRe, katRo, katSmallWa, katWa, 
katWi. katWe, katWo, katN, katVu, katSmallKa, katSmalIKe, escape(255)}; 
Codes46: --XCharSet46-- TYPE = machine dependent{ 

smootheBreathing(37), roughBreathing, iotaScript, upperPrime(52), lowerPrime, 
raised Period (59), upperAlpha(65), upperBeta, upperGamma(68), upperDelta, 
upperEpsilon, upperStigma, upperDigamma, upperZeta, upperEta, upperTheta, 
upperlota, upperKappa, upperLambda, upperMu, upperNu, upperXi, upperOmicron, 
upperPi, upperKoppa, upperRho, upperSigma, al27B, upperTau, upperUpsilon, 
upperPhi, upperKhi, upperPsi, upperOmega, upperSampi, lowerAlpha(97), 
lowerBeta, lowerBetaMiddleWord, lowerGamma, lowerDelta, lowerEpsilon, 
lowerStigma, lowerDigamma, lowerZeta, lowerEta, lowerTheta, lowerlota, 
lowerKappa, lowerLambda, lowerMu, lowerNu, lowerXi, lowerOmicron, lowerPi, 
lowerKoppa, lowerRho, lowerSigma, lowerSigmaMiddleWord, lowerTau, 
lowerUpsilon, lowerPhi, lowerKhi, lowerPsi, lowerOmega, lowerSampi, 
escape(255)}; 
Codes47: -XCharSet47-- type = machine DEPENbENT{ 

upperA(33), upperBe, upperVe, upperGe, upperDe, upperYe, upperYo, upperZhe, 
upperZe, upperl, upperlKratkoye, upperKa, upperEI, upperEm, upperEn, upperO, 
upperPe, upperEr, upperEs, upperTe, upperU, upperEf, upperXa, upperTse, 
upperChe, upperSha, upperShCha, upperTvyordiiZnak, upperYeri, 
upperMyaxkiiZnak, upperEOborotnoye, upperYu, upperYa, lowerA(81), lowerBe, 
lowerVe, lowerGe, lowerDe, lowerYe, lowerYo, lowerZhe, lowerZe, lowerl, 
lowerlKratkoye, lowerKa, lowerEI, lowerEm, lowerEn, lowerO, lowerPe, lowerEr, 
lowerEs, lowerTe, lowerU, lowerEf, lowerXa, lowerTse, lowerChe, lowerSha, 
lowerShCha, lowerTvyordiiZnak, lowerYeri, lowerMyaxkiiZnak, lowerEOborotnoye, 
lowerYu, lowerYa, escape(255)}; 
ColumnContents: --F/7eConta/nerSource-- type = long descriptor for array 

CARDINAL OF ColumnContentslnfo; 
ColumnContentslnfo: --F//eConta/nerSource-- type = record [ 
info: select type: ColumnType from 
attribute = > [ 

attr: NSFile.AttributeType, 

formatProc: AttributeFormatProc " nil, 

needsDataHandle: boolean " false], 
extended Attribute = > [ 

extended Attr : NSFi I e. Extended Attri buteType, 

formatProc: AttributeFormatProc " nil, 

needsDataHandle: boolean " false], 
multipleAttributes = > [ 

attrs: NSFile.Selections, 

formatProc: MultiAttributeFormatProc ' nil, 

needsDataHandle: boolean ' false], 
endcase); 

ColumnCount: --ContainerSource- ColumnCountProc; 
ColumnCountProc: --Conta/nerSource-- type = procedure [source: Handle] 

returns [columns: cardinal]; 
ColumnHeaderlnfo: --Conta/nerW/ndoM/-- type = record [ 

width: cardinal, wrap: boolean ' true, heading: XString.ReaderBodyj; 
ColumnHeaders: -ContainerWindow - type = long descriptor for array cardinal of 

ColumnHeaderlnfo; 
ColumnType: -FileContainerSource- type = { 

attribute, extendedAttribute, multipleAttributes}, 
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CommandProc: -FormWindow- type = procedure [ 

window: Window. Handle, item: ItemKey, clientData: long pointer]; 
Compare: --XLReal- procedure [a: Number, b: Number] returns [Comparison]; 
Compare: -XString- procedure [ 

r1: Reader, r2: Reader, ignoreCase: boolean ^ true, 

sortOrder: SortOrder " standard] returns [Relation]; 
CompareStringsAndStems: -XStr/ng - procedure [ 

r1 : Reader, r2: Reader, ignoreCase; boolean ' true, 

sortOrder: SortOrder ^ standard] 

returns [relation: Relation, equalStems: boolean]; 
Comparison: -XLRea/-- type = {less, equal, greater}; 

compatibility: -eWSAttr/butefypes-- NSFile.ExtendedAttributeType = 10376B; 
Compose: -XMessage- procedure [ 

source: XString. Reader, destination; XString. Writer, args: StringArray]; 
ComposeOne: -XMessage- procedure [ 

source: XString. Reader, destination: XString. Writer, arg: XString. Reader]; 
ComposeOneToFormatHandle: - XMessage - procedure [ 

source: XString. Reader, destination: XFormat.Handle, arg: XString. Reader]; 
ComposeToFormatHandle: - XMessage- procedure [ 

source: XString. Reader, destination: XFormat.Handle, args: StringArray]; 
ComputeEndContext; -XString - procedure [r; Reader] returns [c: Context]; 
ConfirmChoices: -Attention- type - record [ 

yes: XString. Reader, no: XString. Reader]; 
Conic: -Display- procedure [ 

window: Handle,.a: long integer, b: long integer, c: long integer, 

d: long integer, e: long integer, errorTerm: long integer, 

start: Window. Place, stop: Window. Place, errorRef : Window. Place, 

sharpCornered: boolean, unboundedStart: boolean, unboundedStop: boolean, 

lineStyle: LineStyle ' nil, bounds: Window. BoxHandle ' nil]; 
containedin: --eWSAftr/fouterypes-- NSFile. Extended AttributeType = 10400B; 
Context: -XString- type = machine dependent record [ 

suffixSize(0:0..6): [1..2], 

homogeneous(0:7..7); boolean, 

prefix(0:8..15): Environment. Byte]; 
Conversionlnfo: --Se/ect/on- TYPE = record [ 

SELECT type: * from 

convert = > null, 

enumeration = > [proc: procedure [Value] returns [stop; boolean]], 
query = > [query: long descriptor for array cardinal of QueryElement], 
endcase]; 

Dummy: definitions = 
begin 

Convert: -Selection- procedure [ 

target: Target, zone: uncounted zone ' LOOPHOLE[0]] returns [value: Value]; 
Converter: -ProductFactoringProducts- Product = 7; 
Convertlnteger: -(7n/tConvers/on- procedure [ 

n: long integer, inputUnits: Units, outputUnits: Units] 

returns [long integer]; 
Convertltem: -ContainerSource- ConvertltemProc; 
ConvertltemProc: --Conta/nerSource- type = procedure [ 

source: Handle, itemlndex: Itemlndex, n: cardinal * 1, 
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target: Selection. Target, zone: uncounted zone, 

info: Selection. Conversionlnfo ' xxx, changeProc: ChangeProc " nil, 

changeProcData: long pointer " nil] returns (value: Selection. Value]; 
ConvertNumber: -Selection-- procedure [target: Target] 

RETURNS [ok: boolean, number: long unspecified]; 
ConvertProc: -Selection- type = procedure [ 

data: ManagerData, target: Target, zone: uncounted zone, 

info: Conversionlnfo ^ xxx] returns [value: Value]; 
ConvertReal: -UnitConversion- procedure [ 

n: XLReal. Number, inputUnits; Units, outputUnits: Units] 

returns [XLReal. Number]; 
Copy: -Selection- procedure [v: ValueHandle, data: long pointer]; 
CopyMove: -Selection- ValueCopyMoveProc; 
CopyOrMove: -Selection- type = {copy, move}; 
CopyReader: --XStr/ng-- procedure [r: Reader, z: uncounted zone] 

returns [new: Reader]; 
CopyToNewReaderBody: -XString-- procedure [r: Reader, z: uncounted 
zone] 

returns [ReaderBody]; 
CopyToNewWriterBody: -XString- procedure [ 

r: Reader, z: uncounted zone, endContext: Context " unknownContext, 

extra: cardinal " 0] returns [w: WriterBody]; 
Cos; -XLReal- procedure [radians: Number] returns [cos: Number]; 
coversheetOn: -BWSAttributeTypes- NSFile.ExtendedAttributeType = 
10412B; 

CR: --XFormat- procedure [h: Handle " nil, n: cardinal ^ 1]; 

Create: -Catalog - procedure [ 

name: XString. Reader, catalogType: NSFile.Type, 
session: NSFile.Session ' LOOPHOLE[0]] returns [catalog: 

NSFiie. Reference]; 

Create: --Conta/nerW/nc/ow-- procedure [ 

window: Window. Handle, source: ContainerSource. Handle, 
columnHeaders: ColumnHeaders, firstltem: ContainerSource. Itemlndex ^ 0] 

returns [ 

regularMenultems: MenuData.ArrayHandle, 

topPusheeMenultems: MenuData.ArrayHandle]; 
Create: -ContainerWindowExtra- procedure [ 

window: Window. Handle, source: ContainerSource. Handle, 
columnHeaders: ContainerWindow. Column Headers, 
firstltem: ContainerSource. Itemlndex " 0, readonly: boolean ' false] 
returns [ 

regularMenultems: MenuData.ArrayHandle, 
topPusheeMenultems: MenuData.ArrayHandle]; 
Create: -Context - procedure [ 

type: Type, data: Data, proc: DestroyProcType, window: Window. Handle]; 
Create: -FileContainerShell- procedure [ 

file: NSFiie. Reference, columnHeaders: ContainerWindow. ColumnHeaders, 
columnContents: FileContainerSource.ColumnContents, 
regularMenultems: MenuData.ArrayHandle ' xxx, 

topPusheeMenultems: MenuData.ArrayHandle ' xxx, scope; NSFiie. Scope " 
xxx, 

position: ContainerSource. Itemlndex * 0, 

options; FileContainerSource. Options ' LOOPHOLE[0]] 

RETURNS [shell: StarWindowShell. Handle]; 
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Create: --FileContainerSource- procedure [ 

file: NSFile. Reference, columns: ColumnContents, scope: NSFile. Scope " xxx, 
options: Options " LOOPHOLE(0]] returns [source: ContainerSource.Handle]; 

Create: -FormWindow- procedure [ 

window: Window. Handle, makeltemsProc: MakeltemsProc, 

layoutProc: LayoutProc ' nil, windowChangeProc: GlobalChangeProc " nil, 

minDimsChangeProc: MinDimsChangeProc ' nil, 

zone: uncounted zone " LOOPHOLE[0], clientData: long pointer ^ nil]; 

Create: --MessageWindow- procedure [ 

window: Window.Handle, zone: uncounted zone " LOOPHOLE[0], 
lines: cardinal " 10]; 

Create: --PropertySheet - procedure [ 

formWindowltems: FormWindow MakeltemsProc, menultemProc: MenultemProc, 
size: Window. Dims, menultems: Menultems " propertySheetDefaultMenu, 
title: XString. Reader ' nil, placeToDisplay: Window. Place " nullPlace, 
formWindowltemsLayout: FormWindow. LayoutProc ' nil, 
windowAttachedTo; StarWindowShell. Handle ^ LOOPHOLE[0], 
globalChangeProc: FormWindow. GlobalChangeProc " nil, display: boolean ^ true, 
clientData: long pointer " nil, afterTakenDownProc: MenultemProc ' nil, 
zorie: uncounted zone ' LOOPHOLE[0]] returns [shell: StarWindowShell. Handle]; 

Create: --Prototype- procedure [ 

name: XString. Reader, type: NSFile. Type, version: Version, 

subtype: Subtype " 0, size: long cardinal " 0, isDirectory: boolean " false, 

session: NSFile.Session " LOOPHOLE[0]] returns [prototype: NSFile.Handle]; 

Create: -StarWindowShell-- procedure [ 

transitionProc: TransitionProc " nil, name: XString. Reader " nil, 
namePicture: XString. Character " 0, host: Handle " LOOPHOLE[0], 
type: ShellType ^ regular, sleeps: boolean " false, 
considerShowingCoverSheet: boolean ^ true, 
currentlyShowingCoverSheet: boolean ' false, 
pushersAreReadonly: boolean false, readonly: boolean " false, 
scrollData: ScrollData " vanillaScrollData, 
garbageCollectBodiesProc: procedure [Handle] ^ nil, 

isCloseLegalProc: IsCloseLegalProc " nil, bodyGravity: Window. Gravity * nw, 

zone: uncounted zone ' LOOPHOLE[0]] returns [Handle]; 
Create: -Window- procedure [ 

display: DisplayProc, box: Box, parent: Handle ' rootWindow, 

sibling: Handle ^ nil, child: Handle " nil, clearingRequired: boolean " true, 

windowPane: boolean ' false, under: boolean ' false, cookie; boolean " false, 

color: boolean ' false, zone: uncounted zone " LOOPHOLE[0]] 

returns [window: Handle]; 
CreateBody: -StarWindowShell- procedure [ 

sws: Handle, repaintProc: procedure [Window.Handle] " nil, 

bodyNotifyProc; TIP.NotifyProc ' nil, box: Window. Box xxx] 

RETURNS [Window.Handle]; 
CreateCharTable: -TIP- procedure [ 

z: UNCOUNTED zone " LOOPHOLE[0], buffered: boolean ' true] 

.RETURNS [table: Table]; 
Create Desktop: -StarDesktop - procedure [name: XString. Reader] 

RETURNS [fh: NSFile.Handle]; 
CreateField: -SimpleTextEdit- procedure [ 

clientData: long pointer, context- FieldContext, dims: Window. Dims, 

initString: XString. Reader ' nil, 

flushness: SimpleTextDisplay.Flushness ' fromFirstChar, 
streakSuccession: SimpleTextDisplay.StreakSuccession ' fromFirstChar, 
readonly: boolean " false, password: boolean " false, 
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fixedHeight: boolean " false, font: SimpleTextFont.MappedFontHandle " nil, 
backingWriter: XString. Writer ' nil, 

SPECIALKeyboard: BlackKeys. Keyboard " nil] returns [f: Field]; 
CreateFieldContext: SimpleTextEdit- procedure [ 

z: UNCOUNTED ZONE, window: Window. Handle, changeSizeProc: ChangeSizeProc] 

returns [fc: FieldContext]; 
CreateFile: -Catalog - procedure [ 

catalogType: NSFile.Type " 10476B, name: XString. Reader, type: NSFile.Type, 

isDirectory: boolean " false, size: long cardinal ' 0, 

session: NSFile.Session " LOOPHOLE[0]] returns [file: NSFile. Handle]; 
Createltem: -MenuOata-- procedure [ 

zone: uncounted zone, name: XString. Reader, proc: MenuProc, 

itemData: long unspecified ' 0] returns [ItemHandle]; 
CreateLinked: -PropertySheet- procedure [ 

formWindowltems: FormWindow MakeltemsProc, menultemProc: MenultemProc, 

size: Window. Dims, menultems: Menultems " propertySheetDefaultMenu, 

title: XString. Reader " nil, placeToDisplay: Window. Place " nullPlace, 

formWindowltemsLayout: FormWindow. LayoutProc " nil, 

windowAttachedTo: StarWindowShell. Handle " LOOPHOLE[0], 

globalChangeProc: FormWindow. GlobalChangeProc " nil, display: boolean " true, 

linkWindowltems: FormWindow. MakeltemsProc, 

linkWindowltemsLayout: FormWindow. LayoutProc " nil, 

clientData: long pointer ^ nil, afterTakenDownProc: MenultemProc ' nil, 

zone: uncounted zone " LOOPHOLE[0]] returns [shell: StarWindowShell. Handle]; 
CreateMenu: --MenuData - procedure [ 

zone: uncounted zone, title: ItemHandle, array: ArrayHandle, 

copyltemslntoMenusZone: boolean " false] returns [MenuHandle]; 
CreatePerlodicNotify: -TIP- procedure [ 

window: Window. Handle " nil, results: Results, milliseconds: cardinal, 

notifyProc: NotifyProc " nil] returns [PeriodicNotify]; 
CreatePlaceHolderTable: -TIP- procedure [z: uncounted zone ' LOOPHOLE[0]] 

returns [table: Table]; 
CreateProcType: --Context-- type = procedure returns [Data, Destroy ProcType]; 
CreateTable: -TIP- procedure [ 

file: XString. Reader, z: uncounted zone " LOOPHOLE[0], 

contents: XString. Reader " nil] returns [table: Table]; 
Current: -XTime- procedure returns [time: System. GreenwichMeanTime]; 
DashCnt; -Display- cardinal = 6; 

Data: -Conta/nee- type = record [reference: NSFile. Reference " xxx]; 

Data: --Context- type = long pointer; 

DataHandle: -Conta/nee- TYPE = long pointer to Data, 

Date: -XFormat- procedure [ 

h: Handle * nil, time: System. GreenwichMeanTime * LOOPHOLE[1760131 1200B], 

format: DateFormat " dateAndTime]; 
dateAndTime: -XTime- XString. Reader; 
DateColumn: -FileContainerSource - procedure 

returns [multipleAttributes ColumnContentslnfo]; 
DateFormat: -XFormat- TYPE = {dateOnly, timeOnly, dateAndTime}; 
dateOnly: -XTime- XString. Reader; 

DaysOfWeek: -XComSoftMessage type = Keys [monday.. Sunday]; 
Oecase: -XChar- procedure [c: Character] returns [Character]; 
Decimal: -XFormat- procedure [h: Handle * nil, n: long integer]; 
Decimal: -XToken- procedure [h: Handle, signalOnError: boolean " true] 

returns [i: LONG integer]; 
Decimal Format: -XFormat - NumberFormat; 
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Decompose: -X/Wessage-- procedure [source: XString. Reader] 

RETURNS [args: StringArray]; 
DefaultFileConvertProc: --Containee- Selection. ConvertProc; 
defaultGeometry: --KeyboardWindow-- BlackKeys.GeometryTable; 
DefaultLayout: -FormWindow- LayoutProc; 
defaultPicture: -KeyboardWindow - BlackKeys. Picture; 
DefaultPictureProc: -KeyboardWindow BlackKeys. PictureProc; 
defaultTabStops: -FormWindow- TabStops; 
defaultTime: -XTime- System. GreenwichMeanTime; 
Defined: --Cursor- type = Type [blank, column]; 
DeleteAII: ~L/nc/o- procedure; 

DeleteAndShowNextPrevious: -ContainerWindow- procedure [ 

window: Window. Handle, item: ContainerSource.ltemlndex, direction: Direction]; 
OeleteAndShowNextPrevious: -ContainerWindowExtraZ - procedure [ 

window: Window.Handle, item: ContainerSource.ltemlndex, 

direction: ContainerWindow. Direction] 

returns [newOpenShell: StarWindowShell. Handle]; 
Deleteltems: -ContainerSource- DeleteltemsProc; 
DeleteltemsProc: -ContainerSource- type = procedure [ 

source: Handle, itemlndex: Itemlndex, n: cardinal ' 1, 

changeProc: ChangeProc " nil, changeProcData: long pointer " nil]; 
DeleteNltems: -ContainerCache - procedure [ 

cache: Handle, item; cardinal, nitems; cardinal ^ 1]; 
Delimited: -XToken- FilterProcType; 
Dependency: -Event- type [2]; 

Dereference: -XString- procedure [r: Reader] returns [rb: ReaderBody]; 
DescribeOption: -ProductFactoring- procedure [ 

option: Option, desc: XString.Reader, 

prerequisite: Prerequisite " nullPrerequisite]; 
DescribeProduct: - ProductFactoring- procedure [ 

product: Product, desc: XString.Reader]; 
DescribeReader: -XString- Courier. Description; 
DescribeReaderBody: -XString- Courier.Description; 
desktop: -BWSFHeTypes- NSFile.Type = 10400B; 
desktopCatalog: -aWSF/Vefypes-- NSFile.Type == 10400B; 
DesktopProc: ~-/d/eContro/- TYPE = procedure; 
desktopWindowAvailable: -StarDesktop- Atom. atom; 
DestailBody: -StarWindowShell- procedure [body: Window.Handle]; 
Destroy: ~Conta/ne/W/ndow-- procedure [Window.Handle]; 
Destroy: -Context- procedure (type: Type, window: Window.Handle]; 
Destroy: -FormWindow - procedure [window: Window.Handle]; 
Destroy: -MessageWindow - procedure [Window.Handle]; 
Destroy: -StarWindowShell- procedure [sws: Handle]; 
DestroyAII: -Context - procedure [window: Window.Handle]; 
DestroyBody: -StarWindowShell- procedure [body: Window.Handle]; 
DestroyField: -SimpleTextEdit - procedure [f: Field]; 
DestroyFieldContext: -SimpleTextEdit - procedure [fc: FieldContext]; 

END. 



Destroyltem: -FormWindow - procedure [ 

window: Window.Handle, item: ItemKey, repaint: boolean " true]; 
Destroyltem: -MenuData- procedure [zone: uncounted zone, item: ItemHandle]; 
Destroyltems: -FormWindow- procedure [ 

window: Window.Handle, item: long descriptor for array cardinal of ItemKey, 

repaint: boolean ' true]; 
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DestroyMenu: -MenuData - procedure [zone: uncounted zone, menu: MenuHandle]; 

Destroy Messages: -XMessage- procedure [h: Handle]; 

Destroy MsgsProc: --X/Wessage-- type = procedure [clientData: ClientData]; 

Destroy ProcType: --Context-- type = procedure [Data, Window. Handle]; 

DestroyTable: -TIP- procedure [long pointer to Table]; 

DFonts: -ProductFactoringProducts- Product = 3; 

Difficulty: ~Se/ect/on~ type = {easy, moderate, hard, impossible}; 

Digit: ~XL/?ea/- TYPE = [0..9]; 

Digits: -XLReal- type = packed array [0..12] of Digit; 

Dims: -W/nc/ovv-- type = record [w: integer, h: integer]; 

Direction: -Conta/nerW/ndow- TYPE = {next, previous}; 

Discard: -Selection- procedure [saved: Saved, unmark: boolean " true]; 

DisplayProc: ~W/nc/ow~ type = procedure [window: Handle]; 

Divide: -XLReal- procedure [a: Number, b: Number] returns [Number]; 

DoAnUndo: -Undo- procedure; 

DoAnUnundo: -Undo - procedure; 

DoneLookingAtTextitemValue; -FormWindow- procedure [ 

window: Window. Handle, item: ItemKey]; 
DoneWithString: -AtomicProfile- procedure [string: XString. Reader]; 
dontTimeout: -Attention- Process Ticks = 0; 
DoTheGreeterProc: -IdleControl- GreeterProc; 
Double: -XLReal- procedure [Number] returns [Number]; 
DownUp: -Leve/ZV/Ceys- type = Keystations. DownUp; 
DownUp: -r/P~ type = LevellVKeys DownUp; 
DstFunc: -0/sp/ay~ type = BitBlt.DstFunc; 
E: -XLReal- procedure returns [Number]; 
Editlnfo: ~Conta/nerSoL/rce~ type = record [ 

afterltem: Itemlndex, nitems: cardinal]; 
Ellipse: -Display- procedure [ 

window: Handle, center: Window. Place, xRadius: integer, yRadius: integer, 

lineStyle: LineStyle " nil, bounds: Window. BoxHandle * nil]; 
Empty: -XString- procedure [r: Reader] returns [boolean]; 
emptyContext: -XString- Context; 
Enabled: -ProductFactoring- procedure [option: Option] 

returns [enabled; boolean]; 
EntireBox: -Window- procedure [Handle] returns [box: Box]; 
EntryEnumProc: -OptionFile— type = procedure [entry: XString. Reader] 

RETURNS [stop: BOOLEAN " FALSE]; 

Enumerate: -Catalog- procedure [proc: CatalogProc]; 
Enumerate: -Selection- procedure [ 

proc: EnumerationProc, target: Target, data: RequestorData ' nil, 

zone: uncounted zone " LOOPHOLE[0]] returns [aborted: boolean]; 
EnumerateAllMenus: -StarWindowShellExtra - procedure [ 

sws: StarWindowShell. Handle, proc: StarWindowShell.MenuEnumProc]; 
EnumerateDisplayed: -StarWindowShell- procedure [proc: ShellEnumProc] 

returns [Handle " LOOPHOLE[0]]; 
EnumerateDisplayedOfType: --StarM//r7c/owS/7e//- procedure [ 

type: ShellType, proc: ShellEnumProc] returns [Handle " LOOPHOLE[0]]; 
EnumerateEntries: -OptionFile- procedure [ 

section: XString. Reader, callBack: EntryEnumProc, 

file: NSFile. Reference ' xxx]; 
EnumeratelnvalidBoxes: -Window - procedure [window: Handle, proc: BoxEnumProc]; 
EnumerateKey boards: -KeyboardKey- procedure [ 

class: KeyboardClass, enumProc: EnumerateProc]; 
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EnumerateMyDisplayedParasites: StarWindowShell- procedure [ 
sws: Handle, proc: Shell EnumProc] returns [Handle " LOOPHOLE[0]]; 

EnumeratePopupMenus: -StarWindowShell- procedure [ 
sws: Handle, proc: Menu EnumProc]; 

EnumerateProc: --/Ceyboarc/fCey-- type = procedure [ 
keyboard: BlackKeys. Keyboard, class. KeyboardClass] 

RETURNS [stop: BOOLEAN ' FAlSE]; 

EnumerateSections: -OptionFile- procedure [ 

callBack: SectionEnumProc, file: NSFile. Reference ^ xxx]; 
Enumerate String: -AtomicProfiie- procedure [ 

atom: Atom. atom, proc: procedure [XString. Reader]]; 
Enumerate Tree: -Window- procedure [ 

root: Handle, proc: procedure [window: Handle]]; 
EnumerationProc: --5e/ect/on- type = procedure [ 

element: Value, data: RequestorData] returns [stop; boolean " false]; 
Equal: -XLReal- procedure [a: Number, b: Number] returns [boolean]; 
Equal: -XString - procedure [r1 : Reader, r2: Reader] returns [boolean]; 
Equivalent: -XString- procedure [r1 : Reader, r2: Reader] returns [boolean]; 
eraseFlags: -Display- BitBltFlags; 
Error: -Containee- error [ 

msg: XString. Reader " nil, error: error " nil, errorData: long pointer ' nil]; 
Error: -ContainerSource- error [ 

code: ErrorCode, msg: XString. Reader * nil, error: error ' nil, 

errorData: long pointer " nil]; 
Error: -ContainerWindow - error [code: ErrorCode]; 
Error: -Cor7text-- error [code: ErrorCode]; 
Error: --FormWV/ncyow-- error [code: ErrorCode]; 
^^'^ Error: --/Cey6oard/Cey" error [code: ErrorCode]; 

Error: -OptionFile - error [code: ErrorCode]; 

Error: -ProductFactoring- error [type: ErrorType]; 

Error: -PropertySheet - error [code: ErrorCode]; 

Error: -Selection- error [code: ErrorCode]; 

Error: -SimpleTextEdit - error [type: ErrorTypel; 

Error: -StarWindowShell- error [code: ErrorCode]; 

Error: -TIP- error [code: ErrorCode]; 

Error: -Window- error [code: ErrorCode]; 

Error: -XFormat- error [code: ErrorCode]; 

Error: -XLReal- error [code: ErrorCode]; 

Error: -XMessage- error [type: ErrorType]; 

Error: -XString- error [code: ErrorCode]; 

ErrorCode: "Conta/nerSource- type = machine dependent{ 

invalidParameters, accessError, fileError, noSuchltem, other, last(15)}; 
ErrorCode: -ContainerWindow- type = machine dependent{ 

notAContainerWindow, noSuchltem, last(7)}; 
ErrorCode: --Context-- type = {duplicateType, windowlsNIL, tooManyTypes, other}; 
ErrorCode: -FormWindow- type = machine dependent{ 

notAFormWindow, wrongltemType, invalidChoiceNumber, noSuchLine, 

alreadyAFormWindow, invalidltemKey, itemNotOnLine, duplicateltemKey, 

incompatibleLayout, alreadyLaidOut, last(15)}; 
ErrorCode: -KeyboardKey- type = { 

alreadylnSystemKeyboards, notlnSystem Keyboards, insufficientSpace}; 
ErrorCode: -Opt/onF/'/e- TYPE = { 

invalidParameters, inconsistentValue, notFound, syntaxError}; 
ErrorCode: --PropertySheet" TYPE = {notAPropSheet}; 
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ErrorCode: Selection-- type = { 

tooManyActions, tooManyTargets, invalidOperation, operationFailed, didntAbort, 

didntClear}; 
EnorCode: -StarWindowShell- TYPE = { 

desktopNotUp, notASWS, notStarStyle, tooManyWindows}; 
ErrorCode: --r/P-- TYPE = {noSuchPeriodicNotifier, other}; 
ErrorCode: -Window- type - { 

illegalBitmap, illegalFloat, windowNotChildOfParent, whosSlidingRoot, 

noSuchSibling, noUnderVariant, windowlnTree, sizingWithBitmapUnder, 

illegalStack, invalidParameters}; 
ErrorCode: --XFormat-- TYPE = {invalidFormat, nilData}; 
ErrorCode: -XLReat - type = { 

bug, divideSyZero, invalidOperation, notANumber, overflow, underflow, 

unimplemented}; 
ErrorCode: --XStr/ng- TYPE = { 

invalidOperation, multipleCharSets, tooManyBytes, invalidParameter}; 
ErrorType: -ProductFactoring- type = { 

dataNotPound, notStarted, illegalProduct, illegalOption, missingProduct, 

missingOption}; 
ErrorType: -SimpleTextEdit- type = { 

fieldlsNoplace, noRoomlnWriter, lastCharGTfirstChar}; 
ErrorType: -XMessage- type = { 

arrayMismatch, invalidMsgKeyList, invalidStringArray, invalidString, 

notEnoughArguments}; 
EventData: --App//cat/onFo/der-- TYPE = record [ 

applicationFolder: NSFile. Reference, internalName: XString. Reader]; 
EventType: -Event - type = Atom. atom; 
Exp: -XLReal - procedure [Number] returns [Number]; 
ExpandWriter: -XString- procedure [w: Writer, extra; cardinal]; 
Fetch: -Cursor- procedure [h: Handle]; 

FetchFromlype: --Cursor-- procedure [h: Handle, type: Defined]; 

Field: --S/mp/erextfd/t- TYPE = long pointer to FieldObject; 

FieldContext: -SimpleTextEdit- type = long pointer to FieldContextObject; 

FieldContextObject: -SimpleTextEdit - type; 

FieldObject: -SimpleTextEdit- type; 

fiftyPercent: -Display - Brick; 

filedrawerReference: -BWSAttributeTypes - NSFile. ExtendedAttributeType = 
10407B; 

FillProc: -ContamerCache- type = procedure [cache: Handle] 

returns [errored: boolean ^ false]; 
FillResoiveBuffer: -SimpleTextDisplay- procedure [ 

string: XString. Reader, lineWidth: cardinal ' 177777B, 

wordBreak: boolean ' true, streakSuccession: StreakSuccession " fromFirstChar, 
resolve: ResolveBuffer, font: SimpleTextFont.MappedFontHandle " nil] 
returns [width: cardinal, result: Result, rest: XString. ReaderBody]; 

Filtered: -XToken- procedure [ 

h: Handle, data: FilterState, filter: FilterProcType, 

skip: SkipMode ' whiteSpace, temporary: boolean ' true] 

returns [value: XString. ReaderBody]; 

FilterProcType: -Xfo/fen-- type = procedure [ 

c: XChar.Character, data: FilterState] returns [inClass: boolean]; 

FilterState: -Xfo/cen-- type = long pointer to StandardFilterState; 

Find: -Context- procedure [type: Type, window: Window. Handle] returns [Data]; 

Find: -Prototype- procedure [ 

type: NSFile. Type, version: Version, subtype: Subtype " 0, 

session: NSFile. Session " LOOPHOLE[0]] returns [reference: NSFile. Reference]; 
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FindDescriptionFile: -ApplicationFolder- procedure [ 

applicationFolder: NSFile. Handle] returns [descriptionFile: NSFile. Reference]; 
FindOrCreate: -Context-- procedure [ 

type: Type, window: Window. Handle, createProc: CreateProcType] returns [Data]; 
First: -XString- procedure [r: Reader] returns [c: Character]; 
firstAvailableApplicationType: -BWSAttributeTypes- 

NSFile.ExtendedAttributeType = 10505B; 
firstBWSType: --ews^^ttr/buterypes-- NSFile.ExtendedAttribute Type = 10400B; 
firstOldApplicationSpecific: -BWSAttributeTypes- 

NSFile.ExtendedAttributeType = 104148; 
firstSpareBWSType: -BWS/Aitr/bi/terypes-- NSFile. ExtendedAttributeType = 10461B; 
firstStarType: -em/^f/eFypes-- NSFile.Type = 10400B; 
Fix: -XLReal- procedure [Number] returns [long integer]; 
FixdPtNum: -Display- type = machine dependent record [ 

select overlaid * FROM 

wholeThing = > [li(0:0..31): long integer], 

parts = > [frac(0:0..15): cardinal, int(1 :0..1 5): integer], 

endcase]; 

Float: -Window- procedure [window: Handle, temp: Handle, proc: FloatProc]; 

Float: -XLReal- procedure [long integer] returns [Number]; 

FloatProc: -Window-IVPE = procedure [window: Handle] 
RETURNS [place: Place, done: boolean]; 

Flushness: -FormWi ndow- typb = SimpleTextDisplay.Flushness; 

Flushness: -SimpleTextDisplay- type - {flushLeft, flushRight, fromFirstChar}; 

FlushUserlnput: -TIP- procedure; 

FocusTakeslnput: -TIP- procedure returns [boolean]; 

FontNotFounci: -SimpleTextFont- s\gnal [name: XString. Reader]; 

Format: -XTime- procedure [ 

xfh: XFormat.Handle ' nil, time: System. GreenwiclnlVleanTime ^ defaultTime, 
template: XString. Reader " dateAndTime, Itp: LTP " useSystem]; 

formatHandle: -Attention- XFormat.Handle; 

FormatProc: -XFormat- type = procedure [r: XString. Reader, h: Handle]; 
FormatReal: -XLReal- procedure [ 

h: XFormat.Handle ' nil, r: Number, width: natural]; 
FractionPart: -XLReal- procedure [Number] returns [Number], 
Free: -Selection- procedure [v: ValueHandle]; 

Free: -Window- procedure [window: Handle, zone: uncounted zone " LOOPHOLE[0]]; 
FreeBadPhosphorLlst: -Window- procedure [window: Handle]; 
FreeCache: -ContainerCache- procedure [Handle]; 
FreeChoiceHintsProc: --Forml/V/ndoW" type = procedure [ 

window: Window. Handle, item: ItemKey, 

hints: long descriptor for array cardinal of Choicelndex]; 
FreeChoiceltems: -FormWindowMessageParse - procedure [ 

choiceltems: FormWindow.Choiceltems, zone: uncounted zone]; 
FreeContext: -Selection- procedure [v: ValueHandle, zone: uncounted zone]; 
FreeDataProcedure: --Event-- type = procedure [myData: long pointer]; 
FreeMark: -ContainerCache - procedure [mark: Mark]; 

FreeMsgDomainsStorage: -X/V/essage- procedure [msgDomains: MsgDomains]; 
FreeReaderBytes: -XString - procedure [r: Reader, z: uncounted zone]; 
FreeReaderHandle: -XToken ■ procedure [h: Handle] returns [nil: Handle]; 
FreeResolveBuffer: -SimpleTextDisplay- procedure [ResolveBuffer]; 
FreeStd: -Selection- ValueFreeProc; 

FreeStreamHandle: -XToken- procedure [h: Handle] returns [s: Stream. Handle]; 
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FreeTextHintsProc: -FormWindow - type = procedure [ 
window: Window. Handle, item: ItemKey, 

hints: long descriptor for array cardinal of XString.ReaderBody]; 
FreeTokenString: -XToken- procedure [r: XString. Reader] 

returns [nil: XString. Reader ' nil]; 
FreeTree: -Window - procedure [ 

window: Handle, zone: uncounted zone ' LOOPHOLE[0]]; 
FreeWriterBytes: -XString- procedure [w: Writer]; 
FromBlock: -XString- procedure [ 

block: Environment.Block, context: Context " vanillaContext] 

returns [ReaderBodyl; 
FromChar: -XString - procedure [char: long pointer to Character] 

RETURNS [ReaderBody]; 
FromName: -ApplicationFolder- procedure [internalName: XString. Reader] 

RETURNS [applicationFolder: NSFile Reference]; 
FromNSString: -XString- procedure [ 

s: NSString. String, homogeneous: boolean " false] returns [ReaderBody]; 
FromSTRING: -XString- procedure [s; long string, homogeneous: boolean " false] 

returns [ReaderBody]; 
fullUserName: -StarDesktop- Atom atom; 
GenericProc: -Containee- type = procedure [ 

atom: Atom. atom, data: DataHandle, changeProc: ChangeProc " nil, 

changeProcData: long pointer " nil] returns [long unspecified]; 
Geometry Table: --e/ac/c/Ceys- type = long pointer; 
Geometry TableEntry: -KeyboardWindow- type = record [ 

box: Box, key: Keystations, shift: ShiftState]; 
Get; -XMessage- procedure [h: Handle, msgKey: MsgKey] 

returns [msg: XString.ReaderBody]; 
GetAdjustProc: --StarW/ndowShe//-- procedure [sws: Handle] returns [AdjustProc]; 
GetAvaiiabieBodyWIndowOims: -StarWindowShell- procedure [sws: Handle] 

returns [Window. Dims]; 
GetBitmapUnder: -Window- procedure [window: Handle] returns [long pointer]; 
GetBody: -StarWindowShell- procedure [sws: Handle] returns [Window Handle]; 
GetBodyWindowJustFlts: -StarWindowShell- procedure [sws; Handle] 

returns [boolean]; 

GetBOOLEAN: -AtomicProfile- procedure [atom: Atom. atom] returns [boolean]; 
GetBooleanltemValue: -FormWindow- procedure [ 

window: Window. Handle, item: ItemKey] returns [value: boolean]; 
GetBooleanValue: -OptionFile - procedure [ 

section: XString. Reader, entry: XString. Reader, file: NSFile Reference " xxx] 

returns [value: boolean]; 
GetBox: -SimpleTextEdit- procedure [f: Field] returns [box: Window. Box]; 
GetBox: -Window- procedure [Handle] returns [box; Box]; 
GetCachedName- -Containee procfdure [data: DataHandle] 

returns [name: XString.ReaderBody, ticket: Ticket]; 
GetCachedType: -Containee- procedure [data: DataHandle] 

returns [type: NSFile. Type]; 
GetCaretPlace: -SimpleTextEdit- procedure [context: FieldContext] 

returns [place: Window. Place]; 
GetCharProcType: --Xfo/fen-- type = procedure [h: Handle] 

RETURNS [c: XChar.Character]; 
GetCharTranslator: -TIP- procedure [table: Table] returns [o: CharTranslator]; 
GetCharWidth: -SimpleTextDisplay- procedure [ 

char: XChar.Character, font: SimpleTextFont.MappedFontHandle ~ nil] 

returns [width: cardinal]; 
GetChild: -Window- procedure [Handle] returns [Handle]; 
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GetChoiceltemValue: --FormW/ncyow-- PROCEDUF?E [ 
^110^ window: Window.Handle, item; ItemKey] returns [value: Choicelndex]; 

GetClearingRequired: -Window- procedure [Handle] returns [boolean]; 
GetClientData: -FormWindow- procedure [window: Window.Handle] 

returns [clientData: long pointer]; 
GetClientData: -SimpleTextEdit- procedure [f: Field] 

returns [clientData: long pointer]; 
GetContainee: -StarW/nc/ow5/7e//-- procedure [sws: Handle] 

RETURNS [Contai nee. Data]; 
GetContainerSource: -FileContainerShell- procedure [ 

shell: StarWindowShell. Handle] returns [source: ContainerSource.Handle]; 
GetContainerWindow: -FileContainerShell- PHOCEomE [ 

shell: StarWindowShell. Handle] returns [window: Window.Handle]; 
GetCurrentDesktopFile: -StarDesktop- procedure returns [NSFile. Reference]; 
GetCurrentKeyboard: -BlackKeys- procedure returns [current: Keyboard]; 
GetDecimalltemValue: -Form W/ncyow- procedure [ 

window: Window.Handle, item: ItemKey] returns [value: XLReal. Number]; 
GetDefaultlmplementation: --Conta/nee- procedure returns [Implementation]; 
GetDesktopProc: -IdleControl- procedure [atom: Atom. atom] 

returns [DesktopProc]; 
GetDlms: -Window- procedure [Handle] returns [dims: Dims]; 
GetDlsplayProc: -Window- procedure [Handle] returns [DisplayProc]; 
GetDisplayWindow: -KeyboardWindow- procedure returns [Window.Handle]; 
GetFieldContext: -SimpleTextEdit- procedure [f: Field] returns [FieldContext]; 
GetFile: -Catalog- procedure [ 

catalogType: NSFile. Type " 10476B, name: XString. Reader, 

readonly: boolean * false, session: NSFile.Session ' LOOPHOLE[0]] 
^^■•^ returns [file: NSFile. Handle]; 

GetFlushness: -Form W/ndow-- procedure [window: Window.Handle, item; ItemKey] 

returns [old: Flushness]; 
GetFlushness: -SimpleTextEdit- procedure [f: Field] 

returns [SimpleTextDisplay.Flushness]; 
GetFont: -SimpleTextEdit- procedure [f : Field] 

returns [SimpleTextFont.MappedFontHandle]; 
GetFormWindows: -PropertySheet - procedure [shell: StarWindowShell. Handle] 

returns [form; Window.Handle, link; Window.Handle]; 
GetGlobalChangeProc: -FormWindow- procedure (window: Window.Handle] 

RETURNS [proc: GlobalChangeProc]; 
GetGreeterProc: -IdleControl - procedure returns [GreeterProc]; 
GetHandle: --XComSoftA/Jessage-- procedure returns [h: XMessage. Handle]; 
GetHost: -StarW/ndowShe//-- procedure [sws: Handle] returns [Handle]; 
Getlmplementation: -Containee- procedure [NSFile Type] 

returns [Implementation]; 
Getlmplementation; -Undo- procedure returns [Implementation]; 
Getlnfo: -Cursor- procedure returns [info; Info]; 

GetlnputFocus; -SimpleTextEdit- procedure [fc: FieldContext] returns [Field]; 

GetlnputFocus: -TIP- procedure returns [Window.Handle]; 

GetlntegerltemValue; -FormWindow- procedure [ 

window; Window.Handle, item: ItemKey] returns [value: long integer]; 

GetlntegerValue: -OptionFile procedure [ 

section: XString. Reader, entry; XString. Reader, index: cardinal " 0, 
file: NSFile.Reference ' xxx] returns (value: long integer]; 

GetlsCloseLegalProc: -StarWindowShell- procedure [sws: Handle] 
^"""^ RETURNS [IsCloseLegalProc]; 
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Getltemlnfo; --FileContainerSource procedure [ 

source: ContainerSource. Handle, itemlndex: ContainerSource.ltemlndex] 

RETURNS [file: NSFile.Reference, type: NSFile.Type]; 
GetloinDirection: -XChar - procedure [ChaFacter] returns [JoinDirection]; 
GetLength: -ContainerCacheExtra- procedure [cache: ContainerCache. Handle] 

returns [cacheLength: cardinal], 
GetLength: -ContainerSource- GetLengthProc; 

GetLengthProc: -Conta/nerSource- type = procedure [source: Handle] 

returns [length: cardinal, totalOrPartial: TotalOrPartial ' total]; 
GetLimitProc: -StarWindowShell- procedure [sws: Handle] returns [LimitProc]; 
GetList: -XMessage- procedure [ 

h: Handle, msgKeys: MsgKeyList, msgs: Stri ng Array]; 
GetLONGINTEGER: --Atom/cPro^/7e-- procedure [atom: Atom.ATOM] 

returns [long integer]; 
GetManager: -TIP- procedure returns [current: Manager]; 
GetMode: -TIPStar- procedure returns [mode: Mode]; 
GetMultipleChoiceltemValue: -FormW/nc/ow-- procedure [ 

window: Window.Handle, item: ItemKey, zone: uncounted zone] 

returns [value: long descriptor for array cardinal of Choicelndex]; 
GetNextAvailableKey: -FormWindow- procedure [window: Window Handle] 

returns [key: ItemKey]; 
GetNextOutOfProc: -FormWindow- procedure [ 

window: Window Handle, item: ItemKey] returns [NextOutOfProc]; 
GetNextUnobscuredBox: --StarDes/ctop- procedure [height: integer] 

returns [Window.Box]; 
GetNotifyProc: -TIP- procedure [window: Window.Handle] returns [NotifyProc]; 
GetNotifyProcFromTable: -TIP- procedure [table: Table] returns [NotifyProc]; 
GetNthltem: -ContainerCache- procedure [cache: Handle, n: cardinal] 

RETURNS [ItemHandle]; 
GetOpenltem: -ContainerWindow- procedure [window: Window.Handle] 

RETURNS [item: ContainerSource.ltemlndex " 177777B]; 
GetPane; -Window- procedure [Handle] returns [boolean]; 
GetParent: -Window- procedure [Handle] returns [Handle]; 
GetPlace: -TIP- procedure [window: Window.Handle] returns [Window. Place]; 
GetPlaceFromReference: -Star Desktop- procedure [ref: NSFile.Reference] 

returns [Window.Place]; 
GetPName: -Atom- procedure [atom: atom] returns [pName: XString. Reader]; 
GetProp: --Atom- procedure [onto: atom, prop: atom] returns [pair: RefPair]; 
GetPusheeCommands: -StarWindowShell- procedure [sws: Handle] 

RETURNS [ 

bottom: MenuData.MenuHandle, middle: MenuData MenuHandie, 

top: MenuData.MenuHandle]; 
GetReadOnly: -FormWindow - procedure [window: Window.Handle, item; ItemKey] 

RETURNS [readonly: boolean]; 
GetReadOnly: -SimpleTextEdit - procedure [f: Field] 

RETURNS [readonly: boolean]; 
GetReadOnly: StarWindowShell- procedure [sws: Handle] returns [boolean]; 
GetReguiarCommands: --Star\/l//ncyowS/7e//-- procedure [sws: Handle] 

returns [MenuData.MenuHandle]; 
GetResults: --T/PX- procedure [ 

window: Window.Handle, resultsWanted: ResultsWanted ^ nil] 

RETURNS [results: TIP. Results]; 
GetScrollData: -StarWindowShell-- PROCEDURE [sws: Handle] 

RETURNS [scroUData: ScrollData] 
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GetSelection: -ContainerWindow - procedure [window: Window. Handle] 

RETURNS [ 

first: ContainerSource. Item Index, lastPlusOne: ContainerSource.ltemlndex]; 
GetShellFromReference: -StarDesktop-- procedure [ref: NSFile. Reference] 

RETURNS [sws: StarWindowShell. Handle]; 
GetShowKeyboardProc: -Keyboard Key - procedure returns [ShowKeyboardProc]; 
GetSibling: --Window-- procedure [Handle] returns [Handle]; 
GetSleeps: -StarWindowShell- procedure [sws: Handle] returns [boolean]; 
GetSource: --Conta/nerW/ndow-- procedure [window: Window. Handle] 

returns [source: ContainerSource. Handle]; 
GetState: -StarWindowShell- procedure [sws: Handle] returns [State]; 
GetStreakNature: -XChar- procedure [Character] returns [StreakNature]; 
GetStreakSuccession: -FormWindow- procedure [ 

window: Window.,Handle, item: ItemKey] returns [old: StreakSuccession]; 
GetStreakSuccession: -SimpleTextEdit- procedure [f: Field] 

returns [SimpleTextDisplay.StreakSuccession]; 
GetString: -AtomicProfile-- procedure [atom: Atom. atom] 

returns [XString. Reader]; 
GetStringValue: -OptionFile-- procedure [ 

section: XString. Reader, entry: XString. Reader, 

callBack: procedure [value: XString. Reader], index: cardinal " 0, 

file: NSFile. Reference ' xxx]; 
GetTable: -TIP- procedure [window: Window. Handle] returns [Table]; 
GetTable: --HPS tar- procedure [Placeholder] returns [TIP. Table]; 
GetTableLink; -TIP- procedure [from: Table] returns [to: Table]; 
GetTableOpacfty: -TIP- procedure [table: Table] returns [boolean]; 
GetTabStops: -FormW/ndow-- procedure [window: Window. Handle] 

RETURNS [tabStops: TabStops]; 
GetTag: -FormWindow- procedure [window: Window. Handle, item: ItemKey] 

RETURNS [tag: XString. ReaderBody]; 
GetlextltemValue: -FormWindow - procedure [ 

window: Window. Handle, item; ItemKey, zone: uncounted zone] 

RETURNS [value: XString. ReaderBody]; 
GetTransitionProc: -StarWindowShell- procedure [sws: Handle] 

RETURNS [TransitlonProc]; 
GetType: -StarWindowShell - procedure [sws: Handle] returns [ShellType]; 
GetUseBadPhosphor: -Window- procedure [Handle] returns [boolean]; 
GetUserProfile: --Opt/onf/7e-- procedure returns [file: NSFile. Reference]; 
GetValue: -SimpleTextEdit- procedure [f: Field] returns [XString. ReaderBody]; 
GetVisibility: -FormWindow- procedure [window: Window. Handle, item: ItemKey] 

returns [visibility: Visibility]; 
GetWindow: -S/mp/erextfd/t-- procedure [fc: FieldContext] 

returns [window: Window. Handle]; 
GetWindow: --StarDes/ctop-- procedure returns [Window.Handle]; 
GetWindowltemVaiue: -FormWindow - procedure [ 

window: Window.Handle, item: ItemKey] returns [value: Window.Handle]; 
GetWorkstationProfile: -OptionFile- procedure 

RETURNS [file: NSFile. Reference]; 
GetZone: --Forml/V/ndow- procedure [window: Window.Handle] 

RETURNS [zone: uncounted zone]; 
GetZone: -SimpleTextEdit- procedure [fc: FieldContext] 

RETURNS [uncounted ZONE]; 

GetZone: -StarW/ndowS/ie//-~ procedure [sws: Handle] returns [uncounted zone]; 
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GlobalChangeProc: --FormW/ndow-- TYPE = procedure [ 

window: Window. Handle, item: ItemKey, calledBecauseOf: ChangeReason, 

clientData: long pointer]; 
Gravity: -Window- type = {nil, nw, n, ne, e, se, s, sw, w, c, xxx}; 
Gray: -Display- procedure [ 

window: Handle, box: Window. Box, gray: Brick " fiftyPercent, 

dstFunc: DstFunc ' null, bounds: Window. BoxHandle ^ nil]; 
GrayTrapezoid: -O/sp/ay-- procedure [ 

window: Handle, t: Trapezoid, gray: Brick * fiftyPercent, 

dstFunc: DstFunc " null, bounds: Window. BoxHandle ' nil]; 
Greater: -XLReal- procedure [a: Number, b: Number] returns [boolean]; 
GreaterEq: -XLReal- procedure [a: Number, b: Number] returns [boolean]; 
GreeterProc: -/d/eContro/-- TYPE = procedure returns (Atom. atom]; 
Half: -XLReal- procedure [Number] returns [Number]; 
Handle: -ContainerCache- type = long pointer to Object; 
Handle: "Conta/nerSource-- type = long pointer to Procedures; 
Handle: -Cursor- type = long pointer to Object; 
Handle: -Display- type = Window. Handle; 
Handle: --StarW/ndowShe//- TYPE - record [Window.Handle]; 
Handle: --W/ndow-- TYPE = long pointer to Object; 
Handle: -XFormat- type = long pointer to Object; 
Handle: --XMessage-- TYPE = long pointer to Object; 
Handle: --XFo/fen- type = long pointer to Object; 

HasAnyBeenChanged: -Form Window- procedure [window: Window.Handle] 

returns [yes: boolean]; 
HasBeenChanged: -FormWindow- procedure [window: Window.Handle, item: ItemKey] 

returns [yes: boolean]; 
HaveDisplayedParasite: -StarWindowShell- procedure [sws: Handle] 

returns [boolean]; 
Hex: -XFormat- procedure [h: Handle " nil, n: long cardinal]; 
HexFormat: -XFormat- NumberFormat; 
HighllghtThlsKey: -SoftKeys- procedure [ 

window: Window.Handle, key: cardinal * nullKey]; 
HostNumber: -XFormat- procedure [ 

h: Handle " nil, hostNumber: System. HostNumber, format: NetFormat]; 
HowHard: -Selection- procedure [target: Target, enumeration: boolean " false] 

returns [difficulty: Difficulty]; 
IconColumn: -FileContainerSource— procedure 

returns [attribute ColumnContentslnfo]; 
Idle: -/d/eContro/-- procedure; 

ignoreType: --Conta/nee-- NSFile. Type = 37777777777B; 
Implementation: --Conta/nee-- type = record [ 

implementors: long pointer " nil, 

name: XString.ReaderBody " xxx, 

smallPictureProc: SmallPictureProc " nil, 

pictureProc: PictureProc " nil, 

convertProc: Selection. ConvertProc " nil, 

genericProc: GenericProc " nil]; 
Implementation: --C/ndo-- type = record [ 

opportunity: Proc, 

roadblock: procedure (XString. Reader], 
doAnUndo: procedure, 
doAnUnundo: procedure, 
deleteAII: procedure]; 
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IndexFromMark: --ContainerCache- procedure [mark: Mark] 

RETURNS [index: cardinal]; 
Info: -Cursor- TYPE = record [type: Type, hotX: [0..15], hotY: [0..15]]; 
Info: "FileContainerSource- procedure [source: ContainerSource.Handle] 

RETURNS [ 

file: NSFile. Reference, columns: ColumnContents, scope: NSFile.Scope, 
options: Options]; 
Info: -SoftKeys - procedure [window: Window.Handle] 

RETURNS [ 

table: TIP.Table, notifyProc: TIP.NotifyProc, labels: Labels, 
,highlightedKey: cardinal, outlinedKey: cardinal]; 
InitBreakTable: -XString- procedure [ 

r: Reader, stopOrNot: StopOrNot, otherSets: StopOrNot] 

returns [break: BreakTableObject]; 
Initialize: -Window - prqcedure [ 

window: Handle, display: DisplayProc, box: Box, parent: Handle ^ rootWindow, 

sibling: Handle " nil, child: Handle ' nil, clearingRequired: boolean " true, 

windowPane: boolean ' false, under: boolean " false, cookie: boolean " false, 

color: boolean " false]; 
InitiaiizeWlndow: -Window- procedure [ 

window: Handle, display: DisplayProc, box: Box, parent: Handle ' rootWindow, 

sibling: Handle " nil, child: Handle ^ nil, clearingRequired: boolean ' true, 

windowPane: boolean ' false, under: boolean " false, cookie: boolean false, 

color: boolean " false]; 
InsertlntoTree: ~W/ndow~ procedure [window: Handle]; 
Insertltem: -Conta/nerCac/ne- procedure [ 

cache: Handle, before: cardinal, addData: AddData] 

returns [handle: ItemHandle]; 
Insertltem: -FormWindow- procedure [ 

window: Window.Handle, item: ItemKey, line: Line, beforeltem: ItemKey, 

preMargin: cardinal ^ 0, tabStop: cardinal ^ nextTabStop, 

repaint: boolean " true]; 
InsertLine: -FormWindow- procedure [ 

window: Window.Handle, before: Line, spaceAboveLine: cardinal ^ 0] 

returns [line: Line]; 

InstallBody: -StarW/ndowS/7e//- procedure [sws: Handle, body: Window.Handle]; 

InstallFormWindow: -PropertySheet- procedure [ 

shell: StarWindowShell. Handle, menultemProc: Menu Item Proc, 

menultems: Menultems ' propertySheetDefaultMenu, title: XString. Reader " nil, 

formWindow: Window.Handle, afterTakenDownProc: MenultemProc ' nil]; 

InsufficientRoom: -XStr/ng- signal [ 

needsMoreRoom: Writer, amountNeeded: cardinal]; 

IntegerPart: -XLReal- procedure [Number] returns [Number]; 

Interpolator: -Display-TVPB = record [val: FixdPtNum, dVal: FixdPtNum]; 

IntersectBoxes: -Window- procedure [b1 : Box, b2: Box] returns [box: Box]; 

Invalid: -XTime- error; 

InvalidateBox: -Window- procedure [ 

window: Handle, box: Box, clarity: Clarity " isDirty]; 

InvalidateCache: -Conta/nee- procedure [data: DataHandle]; 

InvalidateWholeCache: -Containee procedure; 

InvalidEncoding: -XString- error [ 

invalidReader: Reader, firstBadByteOffset: cardinal]; 

InvalidHandle: -BlackKeys- error; 

InvalidHandle: -SoftKeys- error; 

InvalidNumber: -XString- signal; 

InvalidTable: -f/P- signal [type: TableError, message: XString. Reader]; 
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Invert: -Cu«or- procedure returns [boolean]; 
Invert; --O/sp/ay-- procedure [ 

window: Handle, box: Window. Box, bounds: Window. BoxHandle ' nil]; 
IsBitmapUnderVariant: -Window- procedure [Handle] returns [boolean]; 
IsBodyWindowOutOflnterior: -StarWindowShell - procedure [body: Window.Handle] 

returns [boolean]; 
IsCloseLegal: -StarWindowShell- procedure [ 

sws: Handle, closeAII: boolean ' false] returns [boolean]; 
IsCloseLegalProc: -StarWindowShell- type = procedure [ 

sws; Handle, closeAII: boolean " false] returns [boolean]; 
IsCioseLegalProcReturnsFaise: -StarWindowShell— IsCloseLegalProc; 
IsColorVariant: -Window- procedure [Handle] returns [boolean]; 
IsCookieVariant: -Window- procedure [Handle] returns [boolean]; 
IsDescendantOfRoot: -Window- procedure [Handle] returns [boolean]; 
IsIt; -Cont^inerWindow- procedure [window: Window.Handle] 

returns [yes: boolean]; 
Isit: -FileContainerSource- procedure [source: ContainerSource. Handle] 

returns [boolean]; 

Isit: -FormWindow - procedure [window: Window.Handle] returns [yes: boolean]; 
Isit: -MessageWindow- procedure [Window.Handle] returns [yes: boolean]; 
IsPlacelnBox: -Window- procedure [place: Place, box: Box] returns [boolean]; 
IsSpeciai: -XLReal - procedure [Number] 

RETURNS [yes; boolean, index: Special Index]; 
Item: --A/7entyOata-- type = Privateltem; 

Item: -Xfo/cen-- procedure [h: Handle, temporary: boolean " true] 

RETURNS [value: XString.ReaderBody]; 
ItemClients: -ContainerCache- procedure [item: ItemHandle] 

RETURNS [clientData: long pointer]; 
ItemClientsLength: -ContainerCache- procedure [handle: ItemHandle] 

RETURNS [dataLength: cardinal]; 
ItemOata: -MenuData- procedure [item: ItemHandle] returns [long unspecified]; 
ItemGeneric: -ContainerSource- ItemGenericProc; 
ItemGenericProc: -ContainerSource- type = procedure [ 

source: Handle, itemlndex: Itemlndex, atom: Atom. atom, 

changeProc: ChangeProc " nil, changeProcData: long pointer " nil] 

returns [long unspecified]; 
ItemHandle: -ContainerCache- type = long pointer to ItemObject; 
ItemHandle: --A/fenuData-- type = long pointer to Item; 
Itemlndex: -ContainerCache- procedure [item; ItemHandle] 

returns [index: cardinal]; 
Itemlndex: --Conta/nerSource- type = cardinal; 
ItemKey: -FormWindow- type = cardinal; 
ItemName: -MenuData- procedure [item: ItemHandle] 

returns [name: XString.ReaderBody]; 
ItemNameWidth: --/Wenc/Data- procedure [item: ItemHandle] returns [cardinal]; 
ItemNthString: --Conta/nerCacA7e-- procedure [item: ItemHandle, n: cardinal] 

returns [XString.ReaderBody]; 
ItemObject: -ContainerCache- type; 

ItemProc; --/Weni/Data-- procedure [item: ItemHandle] returns [proc: MenuProc]; 
ItemStringCount: -ContainerCache- procedure [item: ItemHandle] 

returns [strings: cardinal]; 
Item Type: --Form W/ndow-- TYPE = machine dependent{ 

choice, multiplechoice, decimal, integer, boolean, text, command, tagonly, 

window, last(1 5)}; 
Joi nDi recti on : --XChar- type = {nextCharToRight, nextCharToLeft}; 
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KeyBits: -Level IVKeys- type = packed array Key Name of DownUp; 
KeyBits: -r/P" TYPE = Level IVKeys. KeyBits; 

Keyboard: --S/ac/c/Ceys-- type = long pointer to KeyboardObject " nil; 

KeyboardClass: --KeyboardKey-- type = {system, client, special, all, none}; 

KeyboardObject: --S/ac/c/CeyS" TYPE = record [ 
table: TIP.Table ' nil, 
charTranslator: TIP.CharTranslator " xxx, 
pictureProc: PictureProc " nil, 
label: XString.ReaderBody " xxx, 
clientData: long pointer " nil]; 

KeyName: -/.eve//\/R'eys-- TYPE = machine dependent{ 

- notAKey, Keyset1(8), Keyset2, Keysets, Keyset4, Keysets, MouseLeft, 

MouseRight, MouseMiddle, Five, Four, Six, E, Seven, D, U, V, Zero, K, Minus, 
P, Slash, Font, Same, BS, Three, Two, W, Q, S, A, Nine, I, X, O, L, Comma, 
CloseQuote, RightBracket, Open, Keyboard, One, Tab, ParaTab, F, Props, C, J, 
B, Z, LeftShift, Period, SerniColon, NewPara, OpenQuote, Delete, Next, R, T, G, 
Y, H, Eight, N, M, Lock, Space, LeftBracket, Equal, RightShift, Stop, Move, 
Undo, Margins, R9, L10, L7, L4, LI, A9, RIO, A8, Copy, Find, Again, Help, 
Expand, R4, D2, D l, Center, T1, Bold, Italics, Underline, Superscript, 
Subscript, Smaller, T10, R3, Key47, A10, Defaults, A1 1, A1 2}; 

KeyName: -TIP- type = LevellVKeys.KeyName; 

Keys: --XComSoftMessage- TYPE = machine dependent{ 

time, date, dateAndTime, am, pm, January, february, march, april, may, june, 
july, august, September, October, november, december, monday, tuesday, 
Wednesday, thursday, friday, Saturday, Sunday, decimalSeparator, 
thousandsSeparator}; 

Keystations: -KeyboardWindow- type = machine dependent{ 

k1, k2, k3, k4, k5, k6, k7, k8, k9, klO, k1 1, k12, k13, k14, k15, k16, k17, 
k18, kl9, k20, k21, k22, k23, k24, k25, k26, k27, k28, k29., k30, k31 , k32, 
k33, k34, k35, k36, k37, k38, k39, k40, k41 , k42, k43, k44, k45, k46, k47, 
k48, a1, a2, a3, a4, aS, a6. a7, a8, a9, a10, a1 1. a12, last(96)}; 

KeyToCharProc: -TIP- type = procedure [ 

keys: long pointer to KeyBits, key: KeyName, downUp: DownUp, 
data: long pointer, buffer: XString. Writer]; 

Label Record : "Soft/CeyS" type = record [ 

unshifted: XString.ReaderBody ' xxx, shifted: XString.ReaderBody ^ xxx]; 

Labels: --Soft/Ceys-- type = long descriptor for array cardinal of Label Record; 

lasstOldAppiicationSpecific: -BWSAttributeTypes- 
NSFile.ExtendedAttributeType = 10457B; 

lastBWSType: -8WSAttr/bLfterypes-- NSFile.ExtendedAttributeType = 10777B; 

LayoutError: -formW/nc/ovv-- signal [code: LayoutErrorCode]; 

LayoutErrorCode: --Form Wmcyow-- TYPE = {onTopOfAnotherltem, 

notEnufTabsDefined}; 

LayoutlnfoFromltem: -FormW/ndow- procedure [ 
window: Window. Handle, item: ItemKey] 

RETURNS [line: Line, margin: cardinal, tabStop: cardinal, box: Window. Box]; 
LayoutProc: --Form W/ncyoM/-- type = procedure [ 

window: Window. Handle, clientData: long pointer]; 
Less: -XLReal- procedure [a: Number, b: Number] returns [boolean]; 
LessEq: -XLReal- procedure [a: Number, b: Number] returns [boolean]; 
LimitProc: -StarWindowShell- type ~ procedure [sws: Handle, box: Window. Box] 

returns [Window. Box]; 
Line: -Display- procedure [ 

window: Handle, start: Window, Place, stop: Window. Place, 

lineStyle: LineStyle " nil, bounds: Window. BoxHandle " nil]; 
Line: -FormWindow- type [2]; 
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Line: --XFormat- procedure [ 

h: Handle " nil, r: XString. Reader, n: cardinal " 1]; 
Line: -XToken-- FilterProcType; 

LineStyle: -Display-TYPE = long pointer to LineStyleObject; 
Li neStyleObject: --D/sp/ay-- TYPE = record [ 

widths: array [0..5] of cardinal, thickness: cardinal]; 
LineUpBoxes: -FormWindow- procedure [ 

window: Window. Handle, 

items: long descriptor for array cardinal of ItemKey xxx]; 
Ln: -XLReal- procedure [Number] returns [Number]; 
Log: --XZ./?ea/- PROCEDURE [base: Number, arg: Number] returns [Number]; 
logoff: StarDesktop- Atom. atom; 
logon: -StarDesktop— Atom. atom; 

LogonSession: -BWSZone- procedure returns (uncounted zone]; 
logonSession: -BWSZone- uncounted zone; 
LookAtTextltemValue: -FormWindow- procedure [ 

window: Window. Handle, item: ItemKey] returns [value: XString. ReaderBody]; 
Lop: -XString- procedure [r: Reader] returns [c: Character]; 
LosingFocusProc: -TIP- type = procedure [ 

w: Window. Handle, data: long pointer]; 
Lowercase: -XChar- procedure [c: Character] returns [Character]; 
LTP: -XTime- type = record [ 

r: select t: * from 

useSystem = > null, useThese = > [Itp: System. LocalTimeParameters], endcase]; 
mailStatus: -fiVUSAttr/buterypes-- NSFile.ExtendedAttributeType = 1041 IB; 
Make: --Atom- procedure [pName: XString. Reader] returns [atom: atom]; 
Make: -XChar- procedure [set: Environment.Byte, code: Environment. Byte] 

returns [Character]; 
Make: -XCharSetO- procedure [code: CodesO] returns [XChar.Character]; 
Make: -XCharSet164 - procedure [code: Cocles164] returns [XChar.Character]; 
Make: -XCharSet356- procedure [code: Codes356] returns [XChar.Character]; 
Make: -XCharSet357- procedure [code: Codes357] returns [XChar.Character]; 
Make: -XCharSet360- procedure [code: Codes360] returns [XChar.Character]; 
Make: -XCharSetSSI- procedure [code: Codes361] returns [XChar.Character]; 
Make: -XCharSet41- procedure [code: Codes41] returns [XChar.Character]; 
Make: -XCharSet42- procedure [code: Codes42] returns [XChar.Character]; 
Make: --XC/7arSet43-- procedure [code: Codes43] returns [XChar.Character]; 
Make: -XCharSet44- procedure [code: Codes44] returns [XChar.Character]; 
Make: --XC/7arSet45-- procedure [code: Codes45] returns [XChar.Character]; 
Make: -XCharSet46- procedure [code: Codes46] returns [XChar.Character]; 
Make: -XCharSet47- procedure [code: Codes47] returns [XChar.Character]; 
MakeAtom: -Atom- procedure [pName: long string] returns [atom: atom]; 
MakeBooleanltem: -FormWindow- procedure [ 

window: Window. Handle, myKey: ItemKey, tag: XString. Reader " nil, 

suffix: XString. Reader " nil, visibility: Visibility ~ visible, 

boxed: boolean ' true, readonly: boolean " false, 

changeProc: BooleanChangeProc ' nil, label: BooleanltemLabel, 

initBoolean: boolean ' true]; 
MakeChoiceltem: -FormWindow - procedure [ 

window: Window. Handle, myKey: ItemKey, tag: XString. Reader ' nil, 

suffix: XString. Reader ' nil, visibility: Visibility " visible, 

boxed: boolean " true, readonly: boolean * false, values: Choiceltems, 

initChoice: Choicelndex, fullyDisplayed: boolean " true, 

verticallyDisplayed: boolean " false, hintsProc: ChoiceHintsProc " nil, 

changeProc: ChoiceChangeProc " nil, 

outlineOrHighlight: OutlineOrHighlight " highlight]; 



Viewpoint Programmer's Manual 



MakeCommandltem: -FormWindow- procedure [ 

window: Window. Handle, myKey: ItemKey, tag; XString. Reader " nil, 
suffix: XString. Reader " nil, visibility: Visibility " visible, 

boxed: boolean " true, readonly: boolean " false, commandProc: CommandProc, 
commandName: XString. Reader, clientData: long pointer " nil]; 

MakeDecimalltem: -FormWindow- procedure [ 

window: Window. Handle, myKey: ItemKey, tag: XString. Reader " nil, 

suffix: XString. Reader ' nil, visibility: Visibility " visible, 

boxed: boolean " true, readonly: boolean ^ false, signed: boolean ' false, 

width: cardinal, initDecimal: XLReal. Number " xxx, 

wrapUnderTag: boolean " false, hintsProc: TextHintsProc ' nil, 

nextOutOfProc: NextOutOfProc ' nil, displayTemplate: XString. Reader " nil, 

SPECIALKeyboard: BlackKeys. Keyboard ' nil]; 

Makelntegeritem: -FormWindow- procedure [ 

window: Window. Handle, myKey: ItemKey, tag: XString. Reader " nil, 
suffix: XString. Reader ' nil, visibility: Visibility ' visible, 
boxed: boolean true, readonly: boolean " false, signed: boolean " false, 
width: cardinal, initlnteger: long integer ' 0, wrapUnderTag: boolean " false, 
hintsProc: TextHintsProc " nil, nextOutOfProc: NextOutOfProc " nil, 
SPECIALKeyboard: BlackKeys.Keyboard ^ nil]; 

MakeltemsProc: -FormW/nc/ovv-- type = procedure [ 
window: Window. Handle, clientData: long pointer]; 

MakeMenultem: -FormWindow- procedure [ 

window: Window Handle, myKey: ItemKey, tag: XString. Reader " nil, 
suffix: XString. Reader " nil, visibility: Visibility " visible, 
boxed: boolean ' true, menu: MenuData.MenuHandle]; 

MakeMultipieChoiceltem: -FormWindow- procedure [ 

window: Window.Handle, myKey: ItemKey, tag: XString. Reader " nil, 
suffix: XString. Reader " nil, visibility: Visibility " visible, 
boxed: boolean ' true, readonly: boolean ' false, values: Choiceltems, 
initChoice: long descriptor for array cardinal of Choicelndex, 
fullyDisplayed: boolean ' true, verticallyDisplayed: boolean ^ false, 
hintsProc: ChoiceHintsProc ' nil, changeProc: MultipleChoiceChangeProc ' nil, 
outlineOrHighlight: OutlineOrHighlight " highlight]; 

MakeNegative: -Cursor- procedure; 

MakePositive: -Cursor- procedure; 

MakeSpeciai: -XLReal- procedure [index: Speciallndex] returns [Number]; 

MakeTagOnlyltem: --FormW/ndow-- procedure [ 

window: Window.Handle, myKey: ItemKey, tag: XString. Reader, 
visibility: Visibility visible]; 

MakeTextltem: -FormWindow- procedure [ 

window: Window.Handle, myKey: ItemKey, tag: XString. Reader " nil, 

suffix: XString. Reader ' nil, visibility: Visibility ~ visible, 

boxed: boolean " true, readonly; boolean " false, width: cardinal, 

initString: XString. Reader nil, wrapUnderTag: boolean " false, 

password Feedback: boolean " false, hintsProc: TextHintsProc " nil, 

nextOutOfProc: NextOutOfProc * nil, 

SPECIALKeyboard: BlackKeys.Keyboard ' nil]; 

MakeWindowltem: -FormWindow- procedure [ 

window: Window.Handle, myKey: ItemKey, tag: XString. Reader ^ nil, 
visibility: Visibility " visible, boxed: boolean " true, size: Window. Dims, 
nextlntoProc: NextlntoProc " nil] returns [clientWindow: Window.Handle]; 

Manager: -TIP- type = record [ 

table: Table, window: Window.Handle, notify: NotifyProc]; 

Manager Data: -Selection- type = long pointer; 
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Map: -XString- procedure [r: Reader, proc: MapCharProc] 

RETURNS [c: Character]; 
MapAtomProc: -Atom- type = procedure [atom] returns [boolean]; 
MapAtoms: --Atom-- procedure [proc: MapAtomProc] returns [lastAtom: atom]; 
MapCharProc: -XString- type = procedure [c: Character] 

returns [stop: boolean]; 
MappedOefaultFont: -SimpleTextFont- procedure returns [MappedFontHandlej; 
MappedFont: -SimpleTextFont- procedure [name: XString. Reader ^ nil] 

returns [MappedFontHandle]; 
MappedFontDescriptor: -SimpleTextFont- type; 
MappedFontHandle: ~S/mp/erextFont - type = long pointer to 

MappedFontDescriptor; 
MapPList: -Atom- procedure [atom: atom, proc: MapPListProc] 

returns [lastPair: RefPair]; 
MapPListProc: -Atom- type = procedure [RefPair] returns [boolean]; 
Mark: ~Confa/nerCac/)e~ type = long pointer to MarkObject; 
MarkObject: -ContainerCache- type; 

Match: -Selection- procedure [pointer: ManagerData] returns [match: boolean]; 
maxStringLength: -Se/ect/on- CARDINAL = 200; 
MaybeQuoted: -XToken- procedure [ 

h: Handle, data: FilterState, filter: FilterProcType * NonWhiteSpace, 

isQuote: QuoteProcType ' Quote, skip: SkipMode " whiteSpace, 

temporary: boolean " true] returns [value: XString. ReaderBody]; 
MeasureString: -SimpleTextDisplay - procedure [ 

string: XString. Reader, lineWidth: cardinal ' 177777B, 

wordBreak: boolean " true, streakSuccession: StreakSuccession * fromFirstChar, 

font: SimpleTextFont.MappedFontHandle ' nil] 

returns [width: cardinal, result: Result, rest: XString. ReaderBody]; 
MenuArray: -MenuData— procedure [menu: MenuHandle] 

returns [array: ArrayHandle]; 
MenuEnumProc: -StarWindowShell- type = procedure [menu: MenuData. MenuHandle] 

returns [stop: boolean ^ false]; 
MenuHandle: -/WenL/Oata- type = long pointer to MenuObject; 
MenultemProc: -PropertySheet- type = procedure [ 

shell: StarWindowShell. Handle, formWindow: Window. Handle, 

menultem: MenultemType, clientData: long pointer] returns [ok: boolean]; 
Menu Items: -PropertyS/7eet~ type = packed array MenultemType of 

BooleanFalseDefault; 
MenultemType: --PropertySheet-- TYPE = { 

done, apply, cancel, defaults, start, reset}; 
MenuObject: -MeniyData- TYPE = PrivateMenu; 
MenuProc: --/WenuData- TYPE = procedure [ 

window: Window. Handle, menu: MenuHandle, itemData: long unspecified]; 
MenuTitle: -MenuData- procedure [menu: MenuHandle] 

returns [title: ItemHandle]; 
Messages: -XMessage- type = long descriptor for array cardinal of MsgEntry; 
MessagesFromFile: -XMessage- procedure [ 

fileName: long string, clientData: ClientData, proc: DestroyMsgsProc] 

RETURNS [msgDomains: MsgDomains]; 
MessagesFromReference: -X/Wessage - procedure [ 

file: NSFile. Reference, clientData: ClientData, proc: DestroyMsgsProc] 

RETURNS [msgDomains: MsgDomains]; 
Mi nDimsChangeProc: --Form W/ndow- TYPE = procedure [ 

window: Window. Handle, old: Window. Dims, new: Window. Dims]; 
MinusLandBitmapUnder: -Window- type [6]; 
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MinusLandColor: --W/nc/ow-- TYPE [1]; 
MinusLandCookieCutter: -Window- type [2]; 
Mode: -f/PStar-- type = {normal, copy, move, sameAs}; 
ModeChangeProc: -r/PStar-- TYPE = procedure! 

old: Mode, new: Mode, clientData: long pointer]; 
ModifySource: -ContainerWindow- procedure [ 

window: Window. Handle, proc: SourceModifyProc]; 
Months: --XComSo^tiWessage-- type = Keys [january..december]; 
MoreFlavor: StarWindowShell- type = {before, after}; 
MoreScroll Proc : -StarM//ndowSA7e//- type = procedure [ 

sws: Handle, vertical: boolean, flavor: MoreFlavor, amount: cardinal]; 
MouseTransformerProc: -W/ndow-- type = procedure [Handle, Place] 

returns [Handle, Place]; 
Move: -Selection- procedure [v: ValueHandle, data: long pointer]; 
MovelntoWindow: -Cursor- procedure [ 

window: Window. Handle, place: Window. Place]; 
MoveMark: -ContainerCache— procedure [mark: Mark, newlndex: cardinal]; 
MsgDomain: --X/Wessage- TYPE = record [ 

applicationName: XString.ReaderBody, handle: Handle]; 
MsgDomains: -XMessage- type = long descriptor for array cardinal of MsgDomain; 
MsgEntry: -XMessage- type = record [ 

msgKey: MsgKey, 

msg: XString.ReaderBody, 

translationNote: long string ^ nil, 

translatable: boolean " true, 

type: MsgType " userMsg, 

id: MsgID]; . . 

MsgID: "XA/7essage-- TYPE = cardinal; 
MsgKey: -XMessage- type = cardinal; 

MsgKeyList: --X/Wessage- type = long descriptor for array cardinal of MsgKey; 

MsgType: --XMessage- type = { 

userMsg, template, argU'st, menultem, pSheetltem, commandltem, errorMsg, 
infoMsg, promptltem, windowMenuCommand, others}; 

MultiAttributeFormatProc: -FileContainerSource- type = procedure [ 

containeelmpi: Containee. Implementation, containeeData: Containee.DataHandle, 
attrRecord: NSFile.Attributes, displayString: XString. Writer]; 

MultipleChoiceChangeProc: --FormW/ndow-- TYPE = procedure [ 

window: Window. Handle, item; ItemKey, calledBecauseOf: ChangeReason, 
oldValue: long descriptor for array cardinal of Choicelndex, 
newValue: long descriptor for array cardinal of Choicelndex]; 

Multiply: -XLReal- procedure [a: Number, b: Number] returns [Number]; 

NameAndVersionColumn: -FileContainerSourceExtra- procedure 

returns [multipleAttributes FileContainerSource.ColumnContentslnfo]; 

NameColumn: -FileContainerSource- procedure 
returns [attribute ColumnContentslnfo]; 

NeededDlms: -FormWindow- procedure [window: Window. Handle] 
returns [Window. Dims]; 

Negative: -XLReal- procedure [Number] returns [Number]; 

netAddr: --BWSAttnfouterypes-- NSFile.ExtendedAttributeType = 10402B; 

NetFormat: --XFormat" TYPE = {octal, hex, productSoftware}; 

NetworkAddress: -XFormat- procedure [ 

h: Handle ' nil, networkAddress: System. NetworkAddress, format: NetFormat]; 

networkName: --SWSAttr/fouterypes-- NSFile.ExtendedAttributeType = 10404B; 
^'"'^ NetworkNumber: -XFormat- procedure [ 

h: Handle " nil, networkNumber: System. NetworkNumber, format: NetFormat]; 
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New: -Window- procedure [ 

under: boolean ' false, cookie; boolean " false, color: boolean " false, 

zone: uncounted zone " LOOPHOLE[0]] returns [Handle]; 
newlcon: -StarDesktop- Atom. atom; 

NewResolveBuffer: -SimpleTextDisplay- procedure [words: cardinal] 

returns [ResolveBufferj; 
NewStandardCloseEverything: -StarWindowShellExtra- procedure 

returns [ 

numberLeftOpen: cardinal ^ 0, 

lastNotClosed: StarWindowShell. Handle " LOOPHOLE[0]]; 
NewWriterBody: -XString- procedure [maxLength: cardinal, z: uncounted zone] 

returns [WriterBody]; 
NextlntoProc: -FormWindow - type = procedure [ 

window: Window. Handle, item: ItemKey]; 
NextOutOfProc: -FormWindow- type = procedure [ 

window: Window. Handle, item: ItemKey]; 
nextPlace: -StarDesktop- Window.Place; 
nextTabStop: --Form W/nc/ow-- cardinal = 177777B; 
NilData: -Xfo/cen- signal; 
nonQuote: -XToken- XChar. Character = 0; 
NonWhiteSpace: -XToken- FilterProcType; 
NopDestroyProc: -Context- DestroyProcType; 
NopFree: -Selection- ValueFreeProc; 

nopFreeValueProcs: -Selection - readonly long pointer to ValueProcs; 

NormalTable: -TIPStar- procedure returns [TIP.Table]; 

noScrollData: -StarWindowShell- Scroll Data; 

NoSuchAtom: -Atom- error; 

NoSuchDependency: -Event- error; 

not: ~XC/7ar- Character = 177777B; 

noTabStop: -FormWindow cardinal = 177776B; 

NotAProfileFile: -OptionFile- signal; 

NotEq: -XLReal - procedure [a: Number, b: Number] returns [boolean]; 
Notes: -XTime— type = { 

normal, nozone, zonedGuessed, noTime, timeAndZoneGuessed}; 
Notify: -Event- procedure [event: EventType, eventData: long pointer " nil] 

returns [veto: boolean]; 
NotifyProc: -T/P-type = procedure [window: Window. Handle, results: Results]; 
NSChar: -XFormat- procedure [h: Handle * nil, char: NSString Character]; 
NSLine: -XFormat- procedure [ 

h: Handle * nil, s: NSString. String, n: cardinal ' 1]; 
NSString: -XFormat- procedure [h: Handle " nil, s: NSString String]; 
NSStringFromReader: -XString- procedure [r: Reader, z: uncounted zone] 

returns [ns: NSString. String]; 
NSStringObject: -XFormat - procedure [s: long pointer to NSString. String] 

returns [Object]; 
SStringProc: -XFormat- FormatProc; 
NthCharacter: -XString- procedure [r: Reader, n: cardinal] 

returns [c: Character]; 
null: -Atom - atom; 
null: -XChar- Character = 0; 
nullBox: -Window- Box; 
null Data: -Containee- Data; 
nullHandle: -StarWindowShell - Handle; 
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null Item : --Conta/ne/Source - Item Index = 177777B; 
nu I litem Key: "Form W/mdow-- Item Key = Mllll^; 
null Key: --Soft/Ceys-- CARDINAL = Mllll^; 
null Manager: ~-r/P-- Manager; 
nullOption: -ProductFactoring- Option; 
nullPeriodicNotify: -TIP - PeriodicNotify; 
nullPicture: -BlackKeys- bitmap Picture; 
nullPlace: -PropertySheet - Window.Place; 
nullPrerequisite: -ProductFactoring- Prerequisite; 
nullReaderBody: -XString- ReaderBody; 
nullValue: -Selection- Value; 
nullWriterBody: -XString- WriterBody; 
Number: -XFormat- procedure [ 

h: Handle ' nil, n: long unspecified, format: NumberFormat]; 
Number: -XLReal- type [4]; 
Number: -XToken- procedure [ 

h: Handle, radix: cardinal, signalOnError: boolean " true] 

returns [u: long unspecified]; 

NumberFormat: -XFormat- type = record [ 

base: [2.. 36] " 12, 

zerofill: boolean ^ false, 

signed: boolean " false, 

columns: [0..255] " 0]; 

NumberOfltems: -FormWindow- procedure [window: Window. Handle] 
returns [cardinal]; 

numberOfKeys: --Soft/Ceys-- cardinal = 8;. 

NumberToPair: -XL/?ea/- procedure [n: Number, digits: [1..13]]. 

returns [negative: boolean, exp: integer, mantissa: Digits]; 

Numeric: -XToken- FilterProcType; 

Object: -ContainerCache- type; 

Object: --Cursor-- type = record [info: Info, array: UserTerminal.CursorArray]; 
Object: -W/ndow- type [19]; 
Object: -XFormat- type = record [ 
proc: FormatProc, 

context: XString. Context ' LOOPHOLE[0], 
data: ClientData nil]; 
Object: -XMessage- type; 

Object: -XToken- type = machine dependent record [ 
getChar(0:0..31): GetCharProcType, break(2:0.. 1 5): XChar.Character ' 0]; 
ObscuredBySibling: ~W/ndow- procedure [Handle] returns [boolean]; 
Octal: -XFormat- procedure [h: Handle " nil, n: long unspecified]; 
Octal: -XToken- procedure [h; Handle, signalOnError: boolean " true] 

returns [c: long cardinal]; 
OctalFormat: -XFormat- NumberFormat; 

oldDateSent: -BW/SyAttr/fouterypes-- NSFile.ExtendedAttributeType = 10413B; 
Open: -Catalog - procedure [ 

catalogType: NSFile.Type, session: NSFile. Session ^ LOOPHOLE[0]] 

returns [catalog: NSFile. Handle]; 
Opportunity: -Undo- Proc; 
Option; -ProductFactor/ng- type = record [ 

product: Product, productOption: ProductOption]; 
Options: ~F//eConta/nerSource- type = record [readonly: boolean false]; 
optionSheetDefaultMenu: -PropertySheet- Menu Items; 

outbasketPSData: -8\/l/SAttr/buterypes- NSFile. ExtendedAttributeType = 10410B; 
OutlineOrHighlight: -FormW/ndow- type = (outline, highlight}; 
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OutlineThisKey: SoftKeys - procedure [ 

window: Window. Handle, key: cardinal " nullKey]; 
Overflow: -XString- signal; 

owner: --SWSyAttr/buterypes- NSFile.ExtendedAttributeType = 10377B; 
Pack: -XTime- procedure [unpacked: Unpacked, useSystemLTP: boolean ' true] 

RETURNS [time: System. GreenwichMeanTime]; 
Packed: --Xr/me- type = System. GreenwichMeanTime; 
paintFlags: -Display- BitBltFlags; 
paintGrayFlags: --Display - BitBltFlags; 
Pair: -Atom- type = record [prop: atom, value: RefAny]; 
PairToNumber: -XLReal- procedure [ 

negative: boolean, exp: integer, mantissa: Digits] returns [n: Number]; 
Parallelogram: -O/sp/ay- type = record [ 

x: Interpolator, y: integer, w: natural, h: natural]; 
ParseCholceltemMessage: -FormWindowMessageParse - procedure [ 

choiceltemMessage: XString. Reader, zone: uncounted zone] 

RETURNS [choiceltems: FormWindow.Choiceltems]; 
ParseReader: -XTime- procedure [ 

r: XString. Reader, treatNumbersAs: TreatNumbersAs " dayMonthYear] 

RETURNS [time: System. GreenwichMeanTime, notes: Notes, length: cardinal]; 
ParseWithTemplate: -Xr/me- procedure [ 

r: XString. Reader, template: XString. Reader] 

RETURNS [time: System. GreenwichMeanTime, notes: Notes, length: cardinal]; 
PeekForFlushness: -SimpleTextDisplay- procedure [ 

requested Flushness: Flushness, string: XString. Reader] returns [Flushness]; 
PeekForStreakSuccession: -SimpleTextDisplay- procedure [ 

requestedStreakSuccession: StreakSuccession, string: XString. Reader] 

returns [StreakSuccession]; 
PeriodicNotify: -TIP - type [1]; 

Permanent: -BWSZone- procedure returns [uncounted zone]; 
permanent: -BWSZone- uncounted zone; 
PFonts: -ProductFactoringProducts - Product = 4; 
Pi: -XLReal- procedure returns [Number]; 
Picture: -BlackKeys- type = record [ 

variant: select type: PictureType from 

bitmap = > [bitmap; long pointer], text = > [text: XString. Reader], endcase]; 
PictureAction: --i5/acAr/Ceys-- type = {acquire, release}; 
PictureProc: -BlackKeys - type = procedure [ 

keyboard: Keyboard, action: PictureAction] 

returns [picture: Picture * nullPicture, geometry: GeometryTable ' nil]; 
PictureProc: --Conta/nee-- TYPE = procedure [ 

data: DataHandle, window: Window. Handle, box: Window. Box, old: PictureState, 

new: PictureState]; 
PictureReal: -XLReal - procedure [ 

h: XFormat.Handle ' nil, r: Number, template: XString. Reader]; 
PictureState: -Containee- type = { 

garbage, normal, highlighted, ghost, reference, referenceHighlighted}; 
PictureType: --S/ac/c^eys-- type = {bitmap, text}; 

Piece: -XString - procedure [r: Reader, firstChar: cardinal, nChars: cardinal] 

returns [piece: ReaderBody, endContext; Context]; 
Place: -W/ndow- type = UserTerminal. Coordinate; 
Placeholder: --r/PStar - type = { 

mouseActions, keyOverrides, softKeys, keyboardSpecific, blackKeys, sideKeys, 

backstopSpecial Focus}; 
Point: -Display - procedure [window: Handle, point: Window. Place]; 
Pop: StarWindowShell - procedure [popee: Handle] returns [Handle]; 
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PopOrSwap: -StarWindowShell-- type = {pop, swap}; 
PoppedProc: -StarWindowShell- type = procedure [ 

popped: Handle, newShell: Handle, popOrSwap: PopOrSwap ' pop]; 
PopTable: -TlPStar- procedure [Placeholder, TIP.Table]; 
Popup: -PopupMenu- procedure [ 

menu: MenuData.MenuHandle, clients: Window. Handle, showTitle: boolean ^ true, 

place: Window.Place ^ LOOPHOLE[37777777777B]]; 
Post: -Attention- procedure [ 

s: XString. Reader, clear: boolean " true, beep: boolean ^ false, 

blink: boolean " false]; 
Post: -MessageWindow- procedure [ 

window: Window. Handle, r: XString. Reader, clear: boolean " true]; 
PostAndConfirm: -Attention- procedure [ 

s: XString. Reader, clear: boolean ^ true, 

confirmChoices: ConfirmChoices ^ xxx, timeout: Process.Tlcks " dontTimeout, 

beep: boolean ^ false, blink: boolean " false] 

returns [confirmed: boolean, timedOut: boolean]; 
PostSticky: -Attention- procedure [ 

s: XString. Reader, clear: boolean " true, beep: boolean " false, 

blink: boolean " false]; 
PostSTRING: -MessageWindow- procedure [ 

window: Window. Handle, s: long string, clear: boolean " true]; 
Power: -XLReal - procedure [base: Number, exponent: Number] returns [Number]; 
Prerequisite: -ProductFactor/ng- type = record [ 

prerequisiteSpec: boolean " false, option: Option]; 
printingLigatures: --XC/7arSet360- XCharSets.Sets = LOOPHOLE[240]; 
Privateltem: -MenuData- type = private record [ 

proc: MenuProc, 

nameWidth: natural, 

nameBytes: natural, 

body: select hasltemData: boolean from 

false = > [name: packed sequence computed cardinal of Environment.Byte], 
TRUE = > [ 

itemData: long unspecified, 

name: packed sequence computed cardinal of Environment.Byte], 
endcase]; 

PrivateMenu: --/WeniyOata-- TYPE = private record [ 

zone: uncounted zone, 

swapltemProc: SwapltemProc, 

title: ItemHandle ' nil, 

array: ArrayHandle ' xxx, 

arrayAllocatedltemHandles: natural " 0, 

itemslnMenusZone: boolean ' false]; 
Problem; --S/mp/erextf on t - signal [code: ProblemCode]; 
ProblemCode: -SimpleTextFont - type = { 

badFont, clientCharacterCodesExhausted, clientCharacterBitsExhausted}; 
Proc: -Undo- type == procedure [ 

undoProc: procedure [long pointer], destroyProc: procedure [long pointer], 

data: long pointer, size: cardinal ' 0]; 
Procedures: --Conta/nerSource - type = long pointer to ProceduresObject; 
ProceduresObject: -Conta/nerSource-- type = record [ 

actOn: ActOnProc, 

canYouTake: CanYouTakeProc, 

columnCount: ColumnCountProc, 

convertltem: ConvertltemProc, 

deleteltems: DeleteltemsProc, 
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getLength: GetLengthProc, 

itemGeneric: ItemGenericProc, 

stringOfltem: StringOfltemProc, 

take: TakeProc]; 
Product: --ProductFactoring- TYPE - cardinal [0..1 5]; 
Product: -ProductFactoringProducts - type = ProductFactoring. Product; 
Product: -ProductFactoringProductsExtras- type = ProductFactoring. Product; 
ProductOption: -ProductFactoring- type = cardinal [0.. 27]; 
propertySheetDefaultMenu: -PropertySheet- Menultems; 
prototypeCatalog: --BWSF/7e Types-- NSFile.Type = 1; 
PublicZone: -MenuData- procedure returns [uncounted zone]; 
PurgeOld Versions; -Prototype - procedure [ 

type: NSFile.Type, current: Version, subtype: Subtype " 0]; 
Push: -BlackKeys- procedure [keyboard: Keyboard]; 
Push: -SoftKeys- procedure [ 

table: TIP.Table " nil, notifyProc: TIP.NotifyProc " nil, 

labels: Labels xxx, highlightedKey: cardinal " nullKey, 

outlinedKey: cardinal " null Key] returns [window: Window. Handle]; 
Push: -StarWindowShell- procedure [ 

newShell: Handle, topOfStack: Handle ' LOOPHOLE[0], 

poppedProc: PoppedProc ' nil]; 
PushedMe: -StarWindowShellExtra- procedure [pushee: StarWindowShell. Handle] 

returns [pusher: StarWindowShell. Handle]; 
PushedOnMe: StarWindowShellExtra- procedure [pusher: StarWindowShell. Handle] 

returns [pushee: StarWindowShell. Handle]; 
PushTable: -TIPStar- procedure [Placeholder, TIP.Table]; 
PutProp: -Atom- procedure [onto: atom, pair: Pair]; 
Query: -Selection- procedure [ 

targets: long descriptor for array cardinal of QueryElement]; 
QueryElement: -Selection- type = record [ 

target: Target, enumeration: boolean ' false, difficulty: Difficulty " null]; 
Quote: -XToken- QuoteProcType; 

QuoteProcType: -XToken- type - procedure [c: XChar.Character] 

returns [closing: XChar.Character]; 
Reader: -XFormat - procedure [h: Handle " nil, r: XString. Reader]; 
Reader: -XString- type = long pointer to ReaderBody; 

ReaderBody: -XFormat- procedure [h: Handle * nil, rb: XString. ReaderBody]; 
ReaderBody: -XString- type = private machine dependent record [ 

context(0:0.. 15): Context, 

limit(1:0.. 15): CARDINAL, 

offset(2:0..15): cardinal, 

bytes(3:0..31): ReadOnlyBytes]; 
ReaderFromWriter: -XString - procedure [w: Writer] returns [Reader]; 
Readerlnfo: -XString- procedure [r: Reader] 

returns [context: Context, startsWith377B: boolean]; 
ReaderToHandle: -XToken- procedure [r: XString. Reader] returns [h: Handle]; 
ReaderToNumber: -XLReal- procedure [r: XString. Reader] returns [Number]; 
ReaderToNumber: -XString- procedure [ 

r: Reader, radix: cardinal ' 10, signed: boolean " false] 

returns [long integer]; 
ReadNumber: -XLReal- procedure [ 

get: procedure returns [XChar.Character], 

putback: procedure [XChar.Character]] returns [Number]; 
ReadOnlyBytes: -XString- type = long pointer to readonly ByteSequence; 
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Rebuildltem: -FileContainerSourceExtra2- procedure [ 

source: ContainerSource. Handle, item: ContainerSource.ltemlndex]; 

Reconversion: Selection-- s\gnal [target: Target, zone: uncounted zone] 
RETURNS [Value]; 

ReconvertDuringEnumerate: -Se/ection - procedure [ 

target: Target, zone: uncounted zone ^ LOOPHOLE[0]] returns [Value]; 

RefAny: -Atom- type = long pointer; 

referencedType: --BWS>Attnfouterypes-- NSFile.ExtendedAttributeType = 10401 B; 
RefPair: -Atom- type = long pointer to readonly Pair; 

refParentID: -eW/SAttr/bute fypes-- NSFile.ExtendedAttributeType = 10403B; 
refparentTime: --SWSAttnbuterypes- NSFile.ExtendedAttributeType = 10405B; 
RegisterCiientKeyboards: -KeyboardKey- procedure [ 

wantSystem Keyboards: boolean " true, 

SPECIALKeyboard: BlackKeys. Keyboard nil, 

keyboards: long descriptor for array cardinal of BlackKeys.KeyboardObject ^ 
xxx]; 

RegisterMessages: -XMessage- procedure [ 

h: Handle, messages: Messages, stringBodiesAreReal: boolean]; 
Relation: --XStr/ng- TYPE = {less, equal, greater}; 
Release: -Context- procedure [type: Type, window: Window. Handle]; 
Remainder: -XLReaf- procedure [a: Number, b: Number] returns [Number]; 
remoteName: -SWSAttr/buterypes- NSFile.ExtendedAttributeType = 10406B; 
Remove: -BlackKeys- procedure [keyboard: Keyboard]; 
Remove: -SoftKeys- procedure (window: Window.Handle]; 
RemoveClientKeyboards: -KeyboardKey- procedure; 
RemoveDependency: -Event- procedure [dependency: Dependency]; 
RemoveFromSystemKeyboards: -KeyboardKey- procedure [ 

keyboard: BlackKeys. Keyboard]; 
RemoveFromTree; --W/nc/ow-- procedure [Handle]; 
RemoveltemFromLine; -FormWindow- procedure [ 

window: Window.Handle, item: ItemKey, line: Line, repaint: boolean ' true]; 
RemoveMenuitem: -Attention- procedure [item: MenuData.ltemHandle]; 
RemoveProp: -Atom- procedure [onto: atom, prop: atom]; 
Repaint: -FormWindow- procedure [window: Window.Handle]; 
RepaintField: -SimpleTextEdit - procedure [f: Field]; 
Replace: -StarWindowShell Extra- procedure [ 

new: StarWindowShell. Handle, old: StarWindowShell. Handle]; 
ReplaceChars: -SimpleTextEdit- procedure [ 

f: Field, firstChar: cardinal, nChars: cardinal, r: XString. Reader, 

endContext: XString. Context ' LOOPHOLE[255], repaint: boolean " true]; 
replaceFlags: -Display- BitBltFlags; 
replaceGrayFlags: -Display - BitBltFlags; 
Replaceltem: -ContainerCache- procedure [ 

cache: Handle, item: cardinal, addData: AddData] returns [handle: ItemHandle]; 
ReplacePiece: -XString- procedure [ 

w: Writer, firstChar: cardinal, nChars: cardinal, r: Reader, 

endContext: Context " unknownContext]; 
RequestorData: --Se/ect/on- TYPE = long pointer; 

ResetAIIChanged: --Form l/Vmdow-- procedure [window: Window.Handle]; 
ResetCache: -ContainerCache procedure [Handle]; 

ResetChanged: -FormWindow - procedure [window: Window.Handle, item: ItemKey]; 
ResetUserAbort: -TIP- procedure [Window.Handle]; 

ResolveBuffer: -SimpleTextDisplay - type = long descriptor for array [0..0) of 
cardinal; 

Restore: -FormWindow- procedure [window: Window.Handle]; 
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Restore: -Selection- procedure [ 

saved: Saved, mark: boolean " true, unmark: boolean " true]; 
Result: --S/mp/efextD/sp/ay- TYPE = {normal, margin, stop}; 
ResultObject: --f/P-TYPE = record [ 
next: Results, 
body: select type: * from 
atom = > [a: atom], 
bufferedChar = > null, 
coords = > [place: Window. Place], 
int = > [i: long integer], 
key = > [key: KeyName, downUp: DownUp], 

nop = > NULL, 

string = > [rb: XString.ReaderBody], 
time = > [time: System. Pulses], 

endcase]; 

Results: -TIP- type = long pointer to ResultObject; 
ResultsWanted: --r/PX--TYPE = procedure [ 

window: Window. Handle, table: TIP.Table ' nil, results: TIP.Results] 

returns [wanted: boolean]; 
ReturnTlcket: -Containee- procedure [ticket: Ticket]; 
ReturnToNotifier: -TIP- error [string: XString. Reader]; 
ReverseLop: -XString- procedure [ 

r: Reader, endContext: long pointer to Context, 

backScan: BackScanClosure ' xxx] returns [c: Character]; 
ReverseMap: -XString- procedure [r: Reader, proc: MapCharProc] 

returns [c: Character]; 
Roadblock: -Undo- procedure [XString. Reader]; 
root: --8mF/7erypes--NSFile.Type = 10477B; 
Root: -Window- procedure returns [Handle]; 

Root: -XLReal- procedure [index: Number, arg: Number] returns [Number]; 

rootWindow: -Window - readonly Handle; 

Run: -XString- procedure [r: Reader] returns [run; ReaderBody]; 

Save: --Form W/ndoiv-- procedure [window: Window. Handle]; 

SaveAndSet: -Selection- procedure [ 

pointer: ManagerData, conversion: ConvertProc, actOn: ActOnProc, 

unmark: boolean true] returns [old: Saved]; 
Saved: -Selection- type [6]; 
Scan: -XString- procedure [ 

r: Reader, break: BreakTable, option: BreakCharOption] 

RETURNS [breakChar: Character, front: ReaderBody]; 
ScanForCharacter: -XString- procedure [ 

r: Reader, char: Character, option: BreakCharOption] 

returns [breakChar: Character, front: ReaderBody]; 
Scrol I Data : ~StarW/ndowS/7e//~ TYPE = record [ 

displayHorizontal: boolean " false, 

displayVertical: boolean " false, 

arrowScroll: ArrowScrollProc ' nil, 

thumbScroll: ThumbScrollProc " nil, 

moreScroll: MoreScrollProc " nil]; 
SectionEnumProc: -Opt/onf /7e - type = procedure [section: XString. Reader] 

RETURNS [stop: BOOLEAN ' FALSE]; 

Selectltem: -ContainerWindow- procedure [ 

window: Window. Handle, item: ContainerSource.ltemlndex]; 
SelectReference: -StarDesktop- procedure [reference: NSFile. Reference] 

returns [ok: boolean]; 
Semipermanent: -BWSZone- procedure returns [uncounted zone]; 
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semipermanent: --BWSZone- uncounted zone; 

Services2: -ProductFactoringProductsExtras-- Product = 8; 

Services: -ProductFactoringProducts- Product = 1; 

Set: -Context- procedure [type: Type, data: Data, window: Window.Handle]; 
Set: -Cursor- procedure [type: Defined]; 
Set: -Selection- procedure | 

pointer: ManagerData, conversion: ConvertProc, actOn: ActOnProc]; 
Set: -XChar- procedure [c: Character] returns [set: Environment.Byte]; 
SetAdjustProc: -StarWindowShell- procedure [sws: Handle, proc: AdjustProc] 

returns [old: AdjustProc); 
SetAtlChanged: -FormWindow- procedure [window: Window.Handle]; 
SetAttention: -F/P- procedure [ 

window: Window.Handle, attention: AttentionProc]; 
SetBackStoplnputFocus: -TIP - procedure [window: Window.Handle]; 
SetBitmapUnder: -Window- procedure [ 

window: Handle, pointer: long pointer " nil, 

underChanged: UnderChangedProc ^ nil, 

mouseTransformer: MouseTransformerProc ^ nil] returns [long pointer]; 
SetBodyWindowJustFlts: -StarWindowShell- procedure [ 

sws: Handle, yes: boolean]; 
SetBOOLEAN: -AtomicProfile- procedure [atom: Atom.ATOM, boolean: boolean]; 
SetBooleanltemValue: -FormWindow- procedure [ 

window: Window.Handle, item: ItemKey, newValue: boolean, 

repaint: boolean " true]; 
SetBottomPusheeCommands: -StarWindowShell- procedure [ 

sws: Handle, commands: MenuData.MenuHandle]; 
SetCachedName: -Containee - procedure [ 

data: DataHandle, newMame: XString. Reader]; 
SetCachedType: -Containee- procedure [data: DataHandle, newType: NSFile.Type]; 
SetChanged: -FormWindow- procedure [window: Window.Handle, item: ItemKey]; 
SetCharTranslator: -TIP- procedure [table: Table, new: CharTranslator] 

RETURNS [old: CharTranslator]; 
SetChild: -Window- procedure [window: Handle, newChild: Handle] 

RETURNS [oldChild: Handle]; 
SetChoiceltemValue: -FormWindow- procedure [ 

window: Window.Handle, item: ItemKey, newValue: Choicelndex, 

repaint: boolean " true]; 
SetClearingRequired: -Window- procedure [window: Handle, required: boolean] 

RETURNS [old: boolean]; 
SetContainee; --StarW/ndowS/ie//-- procedure [ 

sws; Handle, file: Containee. DataHandle]; 
SetDecimailtemVaiue: -FormWindow- procedure [ 

window: Window.Handle, item: ItemKey, newValue: XLReal. Number, 

repaint: boolean " true]; 
SetDefaultlmplementation: -Containee- procedure [Implementation] 

returns [Implementation]; 
SetDefaultOutputSink: -XFormat - procedure [new: Object] returns [old: Object]; 
SetDesktopProc: -IdleControl- procedure [ 

atom: Atom.ATOM, desktop: DesktopProc]; 
SetDims: -SimpleTextEdit - procedure [f: Field, dims: Window. Dims]; 
SetDlsplayBackgroundProc: --StarDes/ctop-- procedure [procedure [Window.Handle]]; 
SetDispiayProc: -Window- procedure [Handle, DisplayProc] 

returns [DisplayProc]; 
SetFixedHeight: -SimpleTextEdit- procedure [f: Field, fixedHeight: boolean]; 
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SetFlushness: -FormWindow- procedure [ 

window: Window. Handle, item: ItemKey, new: Flushness] 

RETURNS [old: Flushness]; 
SetFlushness: SimpleTextEdit- procedure [ 

f: Field, new: SimpleTextDisplay. Flushness] 

returns [old: SimpleTextDisplay. Flushness]; 
SetFont: SimpleTextEdit - procedure [ 

f: Field, font: SimpleTextFont.MappedFontHandle ' nil]; 
SetGiobalChangeProc: -FormWindow- procedure [ 

window: Window. Handle, proc: GlobalChangeProc] 

returns [old: GlobalChangeProc]; 
Set Greeter Proc: -IdleControl- procedure [new: GreeterProc] 

returns [old: GreeterProc]; 
SetHost: -StarWindowShell - procedure [sws: Handle, host: Handle] 

RETURNS [old: Handle]; 
Setlmplementation: -Containee- procedure [NSFile.Type, Implementation] 

RETURNS [Implementation]; 
Setlmplementation: -Undo-- procedure [Implementation] returns [Implementation]; 
SetlnputFocus: -FormWindow- procedure [ 

window: Window. Handle, item: ItemKey, beforeChar: cardinal ' 177777B]; 
SetlnputFocus: --S/mp/erext£d/t-- procedure [ 

f: Field, beforeChar: cardinal ' 177777B]; 
SetlnputFocus: -TIP - procedure [ 

w: Window. Handle, takeslnput: boolean, newlnputFocus: LosingFocusProc ' nil, 

clientData: long pointer ' nil]; 
SetlntegerltemVatue: -FormWindow- procedure ( 

window: Window. Handle, item: ItemKey, newValue: long integer, 

repaint: boolean * true]; 
SetlsCloseLegalProc: -StarWindowShell- procedure [ 

sws: Handle, proc: IsCIoseLegalProc]; 
SetltemBox: -FormWindow- procedure [ 

window: Window. Handle, item: ItemKey, box: Window. Box]; 
SetltemNameWidth: -MenuData- procedure [item: ItemHandle, width: cardinal]; 
SetltemWidth: -FormWindow - procedure [ 

window: Window. Handle, item: ItemKey, width: cardinal]; 
SetKeyboard: -KeyboardKey- procedure [keyboard: BlackKeys.Keyboard]; 
SetLimitProc: -StarWindowShell- procedure [sws: Handle, proc: LimitProc] 

RETURNS [old: LimitProc]; 
SetLONGINTEGER: -AtomicProfile - procedure [ 

atom: Atom.ATOM, int: long integer]; 
SetManager: -TIP- procedure [new: Manager] returns (old: Manager]; 
SetMark: -ContainerCache- procedure [cache; Handle, index: cardinal] 

returns [mark: Mark]; 
SetMiddlePusheeCommands: -StarWindowShell- procedure [ 

sws: Handle, commands: MenuData. MenuHandle]; 
SetMode: -TlPStar- procedure [ 

mode: Mode, modeChangeProc: ModeChangeProc ~ nil, 

clientData: long pointer ' nil] returns [old: Mode]; 
SetMultipleChoiceltem Value: -FormWindow- procedure [ 

window: Window. Handle, item: ItemKey, 

newValues: long descriptor for array cardinal of Choicelndex, 

repaint: boolean " true]; 
SetName: StarWindowShell- procedure [sws: Handle, name: XString. Reader]; 
SetNamePicture: -StarWindowShell - procedure [ 

sws: Handle, picture: XString. Character]; 
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SetNextOutOfProc: -Form Window- procedure ( 
%^ window: Window.Handle, item: ItemKey, nextOutOfProc: NextOutOfProc] 

RETURNS [old: NextOutOfProc]; 
SetNotifyProc: -TIP- procedure [window: Window.Handle, notify: NotifyProc] 

RETURNS [oldNotify: NotifyProc]; 
SetNotifyProcForTable: -TIP- procedure [table: Table, notify: NotifyProc] 

RETURNS [oldNotify: NotifyProc]; 
SetParent: -Window- procedure [window: Handle, newParent: Handle] 

RETURNS [oldParent: Handle]; 
SetPlace: -SimpleTextEdit- procedure [f: Field, place: Window.Place]; 
SetPref erred Dims: -StarWindowShell- procedure [ 

sws: Handle, dims: Window. Dims]; 
SetPreferredlnteriorDims: --StarW/nc/owShe//fxtra2-- procedure [ 

sws: StarWindowShell. Handle, dims: Window. Dims]; 
SetPref erredPlace: -StarWindowShell- procedure [ 

sws: Handle, place: Window.Place]; 
SetReadOnly: -FormWindow- procedure [ 

window: Window.Handle, item: ItemKey, readonly: boolean] 

returns [old: boolean]; 
SetReadOnly: -SimpleTextEdit- procedure [f : Field, readonly: boolean] 

returns [old: boolean]; 
SetReadOnly: -StarWindowShell- procedure [sws: Handle, yes: boolean]; 
SetRegularCommands: -StarWindowShell- procedure [ 

sws: Handle, commands: MenuData.MenuHandle]; 
Sets: -XCharSets- TYPE = machine dependent{ 

latin, firstUnusedl, lastUnused1(32), jisSymboM, jisSymbol2, extended Latin, 

hiragana, katakana, greek, Cyrillic, firstUserKanji 1 , lastUserKanji 1(47), 

firstLevellKanji, lastLevellKanji(79), firstLevel2Kanji, lastLevel2Kanji(1 15), 

jSymbolS, firstUserKanji2, lastUserKanji2(126), firstUnused2, 

lastUnused2(160), firstReservedl, lastReserved 1(223), arable, Hebrew, 

firstReserved2, lastReserved2(237), generalSymbols2, generalSymbolsl, 

firstRendering, lastRendering(253), userDefined, selectCode}; 
SetScrollData: -StarWindowShell- procedure [sws: Handle, new: Scroll Data] 

returns [old: ScrollData]; 
SetSelection: --Form W/ndow-- procedure [ 

window: Window.Handle, item: ItemKey, firstChar: cardinal " 0, 

lastChar: cardinal * 177777B]; 
SetSelection: -SimpleTextEdit- procedure [ 

f: Field, firstChar: cardinal " 0, lastChar: cardinal ' 177777B]; 
SetShowKeyboardProc: -KeyboardKey- procedure [ShowKeyboardProc]; 
SetSibling: -Window - procedure [window: Handle, newSibling: Handle] 

returns [oldSibling: Handle]; 
SetSleeps: -StarWindowShell Extra - procedure [ 

sws: StarWindowShell. Handle, sleeps: boolean] returns [old: boolean]; 
SetSource: -ContainerWindow - procedure [ 

window: Window.Handle, newSource: ContainerSource. Handle] 

RETURNS [oldSource: ContainerSource. Handle]; 
SetState: -StarWindowShell- procedure [sws: Handle, state: State]; 
SetStreakSuccession: -FormWindow- procedure [ 

window: Window.Handle, item: ItemKey, new: StreakSuccession] 

returns [old: StreakSuccession]; 
SetStreakSuccession: -SimpleTextEdit- procedure [ 
J f: Field, new: SimpleTextDisplay. StreakSuccession] 

RETURNS [old: SimpleTextDisplay. StreakSuccession]; 
SetString: -AtomicProfile- procedure [ 

atom: Atom. atom, string: XString. Reader, immutable: boolean " false]; 
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SetSwapltemProc: -MenuData- procedure [menu: MenuHandle, new: SwapltemProc] 

RETURNS [old: SwapltemProc]; 
SetTable: --f/P-- procedure [window: Window. Handle, table: Table] 

RETURNS [oldTable: Table]; 
SetTableAndNotifyProc: -TIP - procedure [ 

window: Window. Handle, table: Table ' nil, notify: NotifyProc " nil]; 
SetlableLink: -TIP- procedure [from: Table, to: Table] returns [old: Table]; 
SetlableOpacity: -TIP- procedure [table: Table, opaque: boolean] 

returns [oldOpaque: boolean]; 
SetTabStops: -FormWindow- procedure [ 

window: Window. Handle, tabStops: TabStops]; 
SetTextltemValue: --FormW/ndow- procedure [ 

window: Window. Handle, item: ItemKey, newValue: XString. Reader, 

repaint: boolean " true]; 
SetTopPusheeCommands: -StarWindowShell- procedure [ 

sws: Handle, commands: MenuData. MenuHandle]; 
SetTransitionProc: -StarWindowShell- procedure [ 

sws: Handle, new: TransitionProc] returns [old: TransitionProc]; 
SetUseBadPhosphor: -Window- procedure [Handle, boolean] returns [boolean]; 
SetUserAbort: -f/P- procedure [Window Handle]; 
SetValue: -SimpleTextEdit - procedure [ 

f: Field, string: XString. Reader, repaint: boolean " true]; 
SetVisibility: -FormWindow- procedure [ 

window: Window. Handle, item: ItemKey, visibility: Visibility, 

repaint: boolean ^ true]; 
SetWindowltemSize: -FormWindow- procedure [ 

window: Window. Handle, windowltemKey: ItemKey, newSize: Window. Dims]; 
Shel I Enu m Proc : --StarW/nc/owS/7e//-- TYPE = procedure [sws: Handle] 

returns [stop: BOOLEAN " FALSE]; 

ShellFromChild: -StarWindowShell- procedure [child: Window. Handle] 

RETURNS [Handle]; 
ShellType: --StarW/ndowShe//-- TYPE = machine dependent{ 

regular, keyboard, psheet, attention, static, last(1 5)}; 
Shift: -Display- procedure [ 

window: Handle, box: Window. Box, newPlace: Window. Place]; 
ShiftState: -KeyboardWindow- type = {None, One, Two, Both}; 
ShortLifetime: -BWSZone- procedure returns [uncounted zone]; 
shortLifetime: -BWSZone- uncounted zone; 
ShowKeyboardProc: -KeyboardKey - type = procedure; 
Signal: -Containee- signal [ 

msg: XString. Reader * nil, error: error ' nil, errorData: long pointer - nil]; 
Signal: -ContainerSource- signal [ 

code: ErrorCode, msg: XString. Reader " nil, error: error " nil, 

errorData: long pointer " nil]; 
SimpleDestroyProc: --Context-- DestroyProcType; 
Sin: ~XL/?ea/~ procedure [radians: Number] returns [sin: Number]; 
SizeColumn: -FileContainerSource - procedure 

returns [multipleAttributes ColumnContentslnfo]; 
Skip: -XToken- procedure [ 

h: Handle, data: FilterState, filter: FilterProcType, 

skiplnClass: boolean * true]; 
Ski pMode: -Xrofcen- TYPE = {none, whiteSpace, nonToken}; 
SleepOrDestroy: -StarWindowShell - procedure [Handle] returns [Handle]; 
Slide: -Window- procedure [window: Handle, newPlace: Place]; 
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SlideAndSize: -Window- procedure [ 

window: Handle, newBox: Box, gravity: Gravity " nw]; 
SlideAndSizeAndStack: -Window- procedure [ 

window: Handle, newBox: Box, newSibling: Handle, newParent: Handle ^ nil, 

gravity: Gravity " nw]; 
SlideAndStack: -Window- procedure [ 

window: Handle, newPlace: Place, newSibling: Handle, newParent: Handle " nil]; 
SmallPictureProc: -Conta/nee-- type = procedure [ 

data: DataHandle " nil, type: NSFile.Type ^ ignoreType, 

normalOrReference: PictureState] returns [smallPicture: XString. Character]; 
SocketNumber: -XFormat- procedure [ 

h: Handle " nil, socketNumber: System. SocketNumber, format: NetFormat]; 
SortOrder: -XStr/ng-- type = machine dependent{ 

standard, Spanish, Swedish, danish, firstPree, null(255)}; 
SourceModifyProc: -ContainerWindow- type = procedure [ 

window: Window. Handle, source: ContainerSource. Handle] 

returns [changelnfo: ContainerSource. Changeln.fo]; 
spares: --8WS>Attr/buterypes-- CARDINAL = 20; 
Special Index: --X/./?ea/-- type = natural; 
Spinnaker: -ProductFactoringProducts- Product - 2; 
SqRt: -XLReal- procedure [Number] returns [Number]; 
Stack: --W/ndow-- procedure [ 

window: Handle, newSibling: Handle, newParent: Handle " nil]; 
StandardCiose: -StarWindowShell- procedure [sws: Handle] returns [Handle]; 
StandardCloseAll: -StarWindowShell- procedure [sws: Handle] returns [Handle]; 
StandardCloseEverything: -StarWindowShell- procedure 

returns [notClosed: Handle]; 
StandardFilterState: -XroA:en-- type = array [0..1] OF unspecified; 
StandardLimitProc: -StarWindowShell- LimitProc; 
Star: -ProductFactoringProducts- Product - 0; 
State: -StarWindowShell- type = machine dependent{ 

awake, sleeping, dead, last(7)}; 
StatusOfFill: -ContainerCache- procedure [cache: Handle] 

returns [CacheFillStatus]; 
StopOrNot: -XString- type = {stop, not} ^ not; 
Store: -Cursor- procedure [h: Handle]; 
StoreCharacter: -Cursor- procedure [c: XChar.Character]; 
StoreNumber: -Cursor- procedure [n: cardinal]; 

StoreTable: -TIPStar- procedure [Placeholder, TIP. Table] returns [TIP. Table]; 
StreakNature: -XChar- type = {leftToRight, rightToLeft}; 
StreakSuccession: -FormWindow- type = SimpleTextDisplay.StreakSuccession; 
StreakSuccession: --S/mp/erextD/sp/ay~ type = { 

leftToRight, rightToLeft, fromFirstChar}; 
StreamObject: -XFormat- procedure [sH: Stream. Handle] returns [Object]; 
StreamProc: -XFormat- FormatProc; 

StreamToHandle: -XToken- procedure [s: Stream. Handle] returns [h: Handle]; 
String: -XFormat- procedure [h: Handle ^ nil, s: long string]; 
StringArray: -XMessage- type = long descriptor for array cardinal of 

XString. ReaderBody; 
StringlntoBuffer: -SimpleTextDisplay - procedure [ 

string: XString. Reader, bufferProc: BufferProc, lineWidth: cardinal ^ 177777B, 

wordBreak: boolean " true, StreakSuccession: StreakSuccession " fromFirstChar, 

font: SimpleTextFont.MappedFontHandle * nil] 
^'^^ returns [lastLineWidth: cardinal, result: Result, rest: XString. ReaderBody]; 

StrlnglntoWindow: -SimpleTextDisplay - procedure [ 

string: XString. Reader, window: Window. Handle, place: Window. Place, 
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lineWidth: cardinal " Millie, maxNumberOf Lines: cardinal ' 1, 

lineToLineDeltaY: cardinal " 0, wordBreak: boolean * true, 

flags: BitBlt.BitBltFlags " LOOPHOLE[42000B]] 

returns [lines: cardinal, lastLineWidth: cardinal]; 
StringOfltem: -ContainerSource - StringOfltemProc; 
StringOfltemProc: -Conta/nerSource- TYPE = procedure [ 

source: Handle, itemlndex: Itemlndex, stringlndex: cardinal] 

returns [XString. ReaderBody]; 
Stuff Character: -TIP- procedure [ 

window: Window. Handle, char: XString. Character] returns [boolean]; 
Stuff CurrentSeiection: -TIP - procedure [window: Window. Handle] 

returns [boolean]; 

StuffResults: --f/P-- procedure [window: Window.Handle, results: Results]; 
StuffSTRING: -TIP- procedure [window: Window.Handle, string: long string] 

RETURNS [boolean]; 

StuffString: --7"/P-- procedure [window: Window.Handle, string: XString. Reader] 

RETURNS [boolean]; 

StuffTrashBin: -TIP- procedure [window: Window.Handle] returns [boolean]; 
Subtract: --XLRea/-- procedure [a: Number, b: Number] returns [Number]; 
Subtractltem: -MenuData- procedure [menu: MenuHandle, old: ItemHandle]; 
SubtractPopupMenu: -StarWindowShell- procedure [ 

sws: Handle, menu: MenuData. MenuHandle]; 
Subtype: --Prototype- type = cardinal; 

Swap: -S/ac/c/Ceys- procedure [old: Keyboard, new: Keyboard]; 

Swap: --Cursor-- procedure [old: Handle, new: Handle]; 

Swap: -So ft Keys- procedure [ 

window: Window.Handle, table: TIP. Table ^ nil, 

notifyProc: TIP.NotifyProc " nil, labels: Labels * xxx, 

highlightedKey: cardinal " nullKey, outlinedKey: cardinal * nullKey]; 

Swap: -StarWindowShell- procedure [ 

new: Handle, old: Handle, poppedProc: PoppedProc ' nil]; 

SwapExistingFormWindows: -PropertyS/ieet- procedure [ 

shell: StarWindowShell. Handle, new: Window.Handle, apply: boolean ' true, 
newMenultemProc: MenultemProc * nil, newMenultems: Menultems " LOOPHOLE[0], 
newTitle: XString. Reader " nil, newAfterTakenDownProc: MenultemProc ' nil] 
returns [old: Window.Handle]; 

SwapFormWindows: -PropertySheet- procedure [ 

shell: StarWindowShell. Handle, newFormWindowltems: 

FormWindow.MakeltemsProc, 

newFormWindowitemsLayout: FormWindow.LayoutProc * nil, apply: boolean " true, 
destroyOld: boolean * true, newMenultemProc: MenultemProc " nil, 
newMenultems: Menultems ' LOOPHOLE[0], newTitle: XString. Reader ^ nil, 
newGlobalChangeProc: FormWindow.GlobalChangeProc ' nil, 
newAfterTakenDownProc: MenultemProc " nil] returns [old: Window.Handle]; 

Swapltem: -MenuData- procedure [ 

menu: MenuHandle, old: ItemHandle, new: ItemHandle]; 

SwapltemProc: -MenuData- type = procedure [ 

menu: MenuHandle, old: ItemHandle, new: ItemHandle]; 

SwapMenultem: -Attention- procedure [ 

old: MenuData. ItemHandle, new: MenuData. ItemHandle]; 

Switches: -XToken - FilterProcType; 

SyntaxError: --Xfofcen-- signal [r: XString.Reader]; 

system FileCatalog: -8M/SF/7erypes- NSFile.Type = 10476B; 

system FontHeight: -SimpleTextDisplay - readonly cardinal; 
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Table: -r/P-- TYPE = long pointer to TableObject; 
TableError: -f/P-- TYPE = {fileNotFound, badSyntax}; 
TableObject: -TIP- type; 
TabStops: -FormWindow- type = record [ 
variant: select type: Tablype from 
fixed = > [interval: cardinal], 

vary = > [list: long descriptor for array cardinal of cardinal], 
endcase]; 

TabType: -FormW/ndow-- TYPE = {fixed, vary}; 
Take: -ContainerSource-- TakeProc; 

TakeNEXTKey: --FormW/ndouv-- procedure [window: Window. Handle, item: ItemKey]; 

TakeProc: -ContainerSource - type = procedure [ 

source: Hancile, copyOrMove: Selection. CopyOrMove, 
afterHint: Itemlndex nullltem, withinSameSource: boolean " false, 
changeProc: ChangeProc ^ nil, changeProcData: long pointer " nil, 
selection: Selection. ConvertProc ^ nil] returns [ok: boolean]; 

Tan: -XLReal-- procedure [radians: Number] returns [tan: Number]; 

Target: Selection- type = machine dependent{ 

window, shell, subwindow, string, length, position, integer, interpressMaster, 
file, fileType, token, help, keyboard, interscriptScript, interscriptFragment, 
serializedFiie, name, firstFree, last(1023)}; 

textFlags: -Display- BitBltFlags; 

TextHintAction: -FormWindow- type = {replace, append, nil}; 
TextHintsProc: -FormWindow- type = procedure [ 
window: Window. Handle, item; ItemKey] 

RETURNS [ 

hints: long descriptor for array cardinal of XString.ReaderBody, 
freeHints: FreeTextHintsProc, hintAction: TextHintAction " replace]; 
ThumbFlavor: --Starl/V/r)c/owS/7e// type = {downClick, track, upClick}; 
Thu mbScrol I Proc : --StarWmcyowS/ie//-- type = procedure [ 

sws: Handle, vertical: boolean, flavor: ThumbFlavor, m: integer, 
outOfN: integer]; 
Ticket: -Containee- type [2]; 
timeOnly: -XTime- XString. Reader; 

TIPResults: -SimpleTextEdit- procedure [f : Field, results: TIP. Results] 

RETURNS [tooklnputFocus: boolean, changed: boolean]; 
TotalOrPartial: -Conta/nerSource-- type = {total, partial}; 
Trajectory: -Display- procedure [ 

window: Handle, box: Window. Box ^ xxx, proc: Trajectory Proc, 

source: long pointer " nil, bpl: cardinal ^ 16, height: cardinal ^ 16, 

flags: BitBltFlags " bitFlags, missesChildren: boolean " false, 

brick: Brick " xxx]; 
Trajectory Proc: -Display- type = procedure [Handle] 

RETURNS [Window.Box, integer]; 
TransitionProc: --StarW/ndowShe//-- TYPE = procedure [ 

sws: Handle, state: State]; 
Trapezoid: --D/sp/ay - type = record [ 

x: Interpolator, y: integer, w: Interpolator, h; natural]; 
TreatNumbersAs: -Xr/me-- TYPE = { 

dayMonthYear, monthDayYear, yearMonthDay, yearDayMonth, dayYearMonth, 

monthYearDay}; 

TrimBoxStickouts: -Window- procedure [window: Handle, box: Box] returns [Box]; 
TTYObject: -XFormat- procedure [h: TTY. Handle] returns [Object]; 
TTYProc: -XFormat- FormatProc; 
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Type: --Context-- TYPE = machine dependent{ 
all, first, lastAllocatecl(37737B), last(37777B)}; 

Type: -Cursor-- type = machine dependent{ 

blank, bullseye, confirm, ftpBoxes, hourGlass, lib, menu, mouseRed, pointDown, 
pointLeft, pointRight, pointUp, questionMark, scrollDown, scrollLeft, 
scroll LeftRight, scrollRight, scrollUp, scrollUpDown, textPointer, 
grounded Text, move, copy, sameAs, adjust, row, column, last(255)}; 

UnderChangedProc: ~W/ncyow~ TYPE = procedure [Handle, Box]; 

Unintelligible: -XTime - error [vicinity: cardinal]; 

UniqueAction: -Selection- procedure returns [Action]; 

Uniquelarget: -Selection- procedure returns [Target]; 

UniqueType: -Context- procedure returns [type: Type]; 

UniqueType: -Cursor- procedure returns [Type]; 

Units: -UnitConversion- type = machine dependent{ 

inch, mm, cm, mica, point, pixel, pica, didotPoint, cicero, 
seventySecondOfAnlnch, last(1 5)}; 

unknownContext: -XString- Context; 

UnmapFont: -SimpleTextFontExtra- procedure [SimpleTextFont.MappedFontHandlej; 
Unpack: -XTime- procedure [ 

time: System. GreenwichMeanTime ' defaultTime, Itp: LTP " useSystem] 

returns [unpacked: Unpacked]; 
Unpacked: -xr/me- type = record [ 

year: [0..4070B], 

month: [0..1 1], 

day: [0..31], 

hour: [0 .23], 

minute: [0..59], 

second: [0..59], 

weekday: [0..6], 

dst: BOOLEAN, 

zone: System. LocalTimeParameters]; 
UnpostedSwapltemProc: -MenuData- SwapltemProc; 
UnsignedDecimal Format: -XFormat- NumberFormat; 
UntermlnatedQuote: -XToken- signal; 

Update: -ContainerWindow- procedure [window: Window.Handle]; 
Uppercase: -XChar- procedure [c: Character] returns [Character]; 
useGMT: -XTime- useThese LTP; 

UserAbort: -TIP- procedure [Window.Handle] returns [boolean]; 

userPassword : -StarDesktop- Atom. atom; 

useSystem : -XTime - useSystem LTP; 

Valid: -Window- procedure [Handle] returns [boolean]; 

Validate: -Window- procedure [window: Handle]; 

ValidateReader: -XString- procedure [r: Reader]; 

ValidateTree: -Window- procedure [window: Handle ' rootWindow]; 

ValidExponent: -XZ./?ea/-TYPE = [-512.. 511]; 

Value: -Se/ect/on~ TYPE = record [ 

value: long pointer, 

ops: LONG pointer to ValueProcs ~ nil, 

context: long unspecified ' 0]; 
ValueCopyMoveProc: ~Se/ect/on-- TYPE = procedure [ 

v: ValueHandle, op: CopyOrMove, data: long pointer]; 
ValueFreeProc: ~Se/ect/on~TYPE = procedure [v: ValueHandle]; 
ValueHandle: ~Se/ect/on~ TYPE = long pointer to Value; 
ValueProcs: -Se/ect;on~ type = record [ 

free: ValueFreeProc * nil, copyMove: ValueCopyMoveProc ' nil]; 



D-46 



Viewpoint Programmer's Manual 



D 



VanillaArrowScroli: StarWindowShell-- ArrowScrollProc; 

vanillaContext: -XString- Context; 

vanillaScrollData: -StarWindowShell- Scroll Data; 

VanillaThumbScroll: --StarW/ndowShe//-- ThumbScrollProc; 

version: -SWSAftr/foiuterypes-- NSFile.ExtendedAttributeType = 10460B; 

Version: --Prototype- TYPE == cardinal; 

VersionColumn: -FileContainerSourceExtra- procedure 

RETURNS [attribute FileContainerSource.ColumnContentslnfo]; 
Viewpoint: -ProductFactoringProducts~Pro6uct = 5; 
ViewPointApps: -ProductFactoringProducts- Product = 6; 
Visibility: -FormWindow- type = {visible, invisible, invisibleGhost}; 
WaitSeconds: -TIP- procedure [seconds: cardinal]; 
When: -StarWindowShell- type - {before, after}; 
White: -Display- procedure [ 

window: Handle, box: Window. Box, bounds: Window. BoxHandle ' nil]; 
WhiteSpace: -XToken- FilterProcType; 

WordsForBitmapUnder: -Window- procedure [window: Handle] returns [cardinal]; 
Writer: -XString- type = long pointer to WriterBody; 
WriterBody: -XString- type = private machine dependent record [ 

context(0:0..15): Context, 

limit(1 :0..15): cardinal, 

offset(2:0..15): cardinal, 

bytes(3:0..31): Bytes, 

maxLimit(5:0..15): cardinal, 

endContext(6:0..15): Context, 

zone(7:0..31): uncounted zone]; 
WriterBody FromBlock: - XStr/ng- procedure [ 

block: EnvironmentBlock, inUse: cardinal " 0] returns [WriterBody]; 
WriterBodyFromNSString; -XString- procedure [ 

s: NSString. String, homogeneous: boolean " false] returns [WriterBody]; 
WriterBodyFromSTRING: -XString- procedure ( 

s: LONG string, homogeneous: boolean ' false] returns [WriterBody]; 
Writerlnfo: -XString- procedure [w: Writer] 

returns [unused: cardinal, endContext: Context, zone: uncounted zone]; 
WrIterObject: -XFormat- procedure [w: XString. Writer] returns [Object]; 
WriterProc: -XFormat - FormatProc; 

XFormatObject: --A/7essageW/ncyow-- procedure [window: Window. Handle] 

returns [o: XFormatObject]; 
xorBoxFlags: -Display- BitBltFlags; 
xorFlags: -Display- BitBltFlags; 
xorGrayFlags: -Display- BitBltFlags; 
zero: -XLReal- Number; 

Zone: -Undo- procedure returns [uncounted zone]; 
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